@zhin.js/core 1.0.0 → 1.0.2

package/src/cron.ts

@@ -0,0 +1,176 @@
+import { CronExpressionParser, CronExpression } from 'cron-parser';
+
+/**
+ * Cron 定时任务类
+ * 基于 cron-parser 实现的定时任务调度器
+ */
+export class Cron {
+  private expression: CronExpression;
+  private callback: () => void | Promise<void>;
+  private timeoutId?: NodeJS.Timeout;
+  private isRunning = false;
+  private isDisposed = false;
+
+  /**
+   * 创建一个新的 Cron 实例
+   * @param cronExpression - Cron 表达式 (例如: '0 0 * * *' 表示每天午夜执行)
+   * @param callback - 要执行的回调函数
+   */
+  constructor(cronExpression: string, callback: () => void | Promise<void>) {
+    try {
+      this.expression = CronExpressionParser.parse(cronExpression);
+      this.callback = callback;
+    } catch (error) {
+      throw new Error(`Invalid cron expression "${cronExpression}": ${(error as Error).message}`);
+    }
+  }
+
+  /**
+   * 启动定时任务
+   */
+  run(): void {
+    if (this.isDisposed) {
+      throw new Error('Cannot run a disposed cron job');
+    }
+
+    if (this.isRunning) {
+      return; // 已经在运行中
+    }
+
+    this.isRunning = true;
+    this.scheduleNext();
+  }
+
+  /**
+   * 停止定时任务
+   */
+  stop(): void {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = undefined;
+    }
+    this.isRunning = false;
+  }
+
+  /**
+   * 销毁定时任务，释放资源
+   */
+  dispose(): void {
+    this.stop();
+    this.isDisposed = true;
+  }
+
+  /**
+   * 获取下一次执行时间
+   */
+  getNextExecutionTime(): Date {
+    if (this.isDisposed) {
+      throw new Error('Cannot get next execution time for a disposed cron job');
+    }
+    
+    // 重置表达式到当前时间
+    this.expression.reset();
+    return this.expression.next().toDate();
+  }
+
+  /**
+   * 检查任务是否正在运行
+   */
+  get running(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * 检查任务是否已被销毁
+   */
+  get disposed(): boolean {
+    return this.isDisposed;
+  }
+
+  /**
+   * 获取原始的 cron 表达式字符串
+   */
+  get cronExpression(): string {
+    return this.expression.stringify();
+  }
+
+  /**
+   * 调度下一次执行
+   */
+  private scheduleNext(): void {
+    if (!this.isRunning || this.isDisposed) {
+      return;
+    }
+
+    try {
+      // 重置到当前时间并获取下一次执行时间
+      this.expression.reset();
+      const nextDate = this.expression.next().toDate();
+      const now = new Date();
+      const delay = nextDate.getTime() - now.getTime();
+
+      // 如果延迟时间为负数或0，说明应该立即执行
+      if (delay <= 0) {
+        this.executeCallback();
+        return;
+      }
+
+      // 设置定时器
+      this.timeoutId = setTimeout(() => {
+        this.executeCallback();
+      }, delay);
+
+    } catch (error) {
+      console.error(`Error scheduling next cron execution: ${(error as Error).message}`);
+      // 如果出错，停止任务
+      this.stop();
+    }
+  }
+
+  /**
+   * 执行回调函数并调度下一次执行
+   */
+  private async executeCallback(): Promise<void> {
+    if (!this.isRunning || this.isDisposed) {
+      return;
+    }
+
+    try {
+      // 执行回调函数
+      await this.callback();
+    } catch (error) {
+      console.error(`Error executing cron callback: ${(error as Error).message}`);
+    }
+
+    // 调度下一次执行
+    this.scheduleNext();
+  }
+}
+
+/**
+ * Cron 表达式格式说明:
+ * 
+ * 标准格式: "秒 分 时 日 月 周"
+ * 
+ * 字段说明:
+ * - 秒: 0-59
+ * - 分: 0-59  
+ * - 时: 0-23
+ * - 日: 1-31
+ * - 月: 1-12 (或 JAN-DEC)
+ * - 周: 0-7 (0和7都表示周日，或 SUN-SAT)
+ * 
+ * 特殊字符:
+ * - 星号: 匹配任意值
+ * - 问号: 用于日和周字段，表示不指定值
+ * - 横线: 表示范围，如 1-5
+ * - 逗号: 表示列表，如 1,3,5
+ * - 斜杠: 表示步长，如 0/15 表示每15分钟
+ * 
+ * 常用示例:
+ * - "0 0 0 * * *": 每天午夜执行
+ * - "0 0/15 * * * *": 每15分钟执行  
+ * - "0 0 12 * * *": 每天中午12点执行
+ * - "0 0 0 1 * *": 每月1号午夜执行
+ * - "0 0 0 * * 0": 每周日午夜执行
+ */

package/src/errors.ts

@@ -0,0 +1,365 @@
+// ============================================================================
+// 错误处理系统
+// ============================================================================
+
+/**
+ * 基础错误类，所有自定义错误都应该继承此类
+ */
+export class ZhinError extends Error {
+    public readonly code: string
+    public readonly timestamp: Date
+    public readonly context?: Record<string, any>
+
+    constructor(message: string, code: string = 'ZHIN_ERROR', context?: Record<string, any>) {
+        super(message)
+        this.name = this.constructor.name
+        this.code = code
+        this.timestamp = new Date()
+        this.context = context
+        
+        // 确保错误堆栈正确显示
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor)
+        }
+    }
+
+    /**
+     * 转换为JSON格式
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            timestamp: this.timestamp.toISOString(),
+            context: this.context,
+            stack: this.stack
+        }
+    }
+
+    /**
+     * 转换为用户友好的格式
+     */
+    toUserString(): string {
+        return `[${this.code}] ${this.message}`
+    }
+}
+
+/**
+ * 配置相关错误
+ */
+export class ConfigError extends ZhinError {
+    constructor(message: string, context?: Record<string, any>) {
+        super(message, 'CONFIG_ERROR', context)
+    }
+}
+
+/**
+ * 插件相关错误
+ */
+export class PluginError extends ZhinError {
+    public readonly pluginName: string
+
+    constructor(message: string, pluginName: string, context?: Record<string, any>) {
+        super(message, 'PLUGIN_ERROR', { ...context, pluginName })
+        this.pluginName = pluginName
+    }
+}
+
+/**
+ * 适配器相关错误
+ */
+export class AdapterError extends ZhinError {
+    public readonly adapterName: string
+    public readonly botName?: string
+
+    constructor(message: string, adapterName: string, botName?: string, context?: Record<string, any>) {
+        super(message, 'ADAPTER_ERROR', { ...context, adapterName, botName })
+        this.adapterName = adapterName
+        this.botName = botName
+    }
+}
+
+/**
+ * 连接相关错误
+ */
+export class ConnectionError extends ZhinError {
+    public readonly retryable: boolean
+
+    constructor(message: string, retryable: boolean = true, context?: Record<string, any>) {
+        super(message, 'CONNECTION_ERROR', { ...context, retryable })
+        this.retryable = retryable
+    }
+}
+
+/**
+ * 消息处理错误
+ */
+export class MessageError extends ZhinError {
+    public readonly messageId?: string
+    public readonly channelId?: string
+
+    constructor(message: string, messageId?: string, channelId?: string, context?: Record<string, any>) {
+        super(message, 'MESSAGE_ERROR', { ...context, messageId, channelId })
+        this.messageId = messageId
+        this.channelId = channelId
+    }
+}
+
+/**
+ * 上下文相关错误
+ */
+export class ContextError extends ZhinError {
+    public readonly contextName: string
+
+    constructor(message: string, contextName: string, context?: Record<string, any>) {
+        super(message, 'CONTEXT_ERROR', { ...context, contextName })
+        this.contextName = contextName
+    }
+}
+
+/**
+ * 验证错误
+ */
+export class ValidationError extends ZhinError {
+    public readonly field?: string
+    public readonly value?: any
+
+    constructor(message: string, field?: string, value?: any, context?: Record<string, any>) {
+        super(message, 'VALIDATION_ERROR', { ...context, field, value })
+        this.field = field
+        this.value = value
+    }
+}
+
+/**
+ * 权限错误
+ */
+export class PermissionError extends ZhinError {
+    public readonly userId?: string
+    public readonly requiredPermission?: string
+
+    constructor(message: string, userId?: string, requiredPermission?: string, context?: Record<string, any>) {
+        super(message, 'PERMISSION_ERROR', { ...context, userId, requiredPermission })
+        this.userId = userId
+        this.requiredPermission = requiredPermission
+    }
+}
+
+/**
+ * 超时错误
+ */
+export class TimeoutError extends ZhinError {
+    public readonly timeoutMs: number
+
+    constructor(message: string, timeoutMs: number, context?: Record<string, any>) {
+        super(message, 'TIMEOUT_ERROR', { ...context, timeoutMs })
+        this.timeoutMs = timeoutMs
+    }
+}
+
+/**
+ * 错误处理器接口
+ */
+export interface ErrorHandler {
+    (error: Error, context?: Record<string, any>): void | Promise<void>
+}
+
+/**
+ * 错误管理器
+ */
+export class ErrorManager {
+    private handlers: Map<string, ErrorHandler[]> = new Map()
+    private globalHandlers: ErrorHandler[] = []
+
+    /**
+     * 注册错误处理器
+     */
+    register(errorType: string, handler: ErrorHandler): void {
+        if (!this.handlers.has(errorType)) {
+            this.handlers.set(errorType, [])
+        }
+        this.handlers.get(errorType)!.push(handler)
+    }
+
+    /**
+     * 注册全局错误处理器
+     */
+    registerGlobal(handler: ErrorHandler): void {
+        this.globalHandlers.push(handler)
+    }
+
+    /**
+     * 处理错误
+     */
+    async handle(error: Error, context?: Record<string, any>): Promise<void> {
+        // 首先调用全局处理器
+        for (const handler of this.globalHandlers) {
+            try {
+                await handler(error, context)
+            } catch (handlerError) {
+                // console.error 已替换为注释
+            }
+        }
+
+        // 然后调用特定类型的处理器
+        const errorType = error.constructor.name
+        const handlers = this.handlers.get(errorType) || []
+        
+        for (const handler of handlers) {
+            try {
+                await handler(error, context)
+            } catch (handlerError) {
+                // console.error 已替换为注释
+            }
+        }
+    }
+
+    /**
+     * 移除错误处理器
+     */
+    unregister(errorType: string, handler: ErrorHandler): boolean {
+        const handlers = this.handlers.get(errorType)
+        if (handlers) {
+            const index = handlers.indexOf(handler)
+            if (index !== -1) {
+                handlers.splice(index, 1)
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * 清理所有处理器
+     */
+    clear(): void {
+        this.handlers.clear()
+        this.globalHandlers.length = 0
+    }
+}
+
+/**
+ * 错误重试工具
+ */
+export class RetryManager {
+    /**
+     * 执行重试逻辑
+     */
+    static async retry<T>(
+        fn: () => Promise<T>,
+        options: {
+            maxRetries?: number
+            delay?: number
+            exponentialBackoff?: boolean
+            retryCondition?: (error: Error) => boolean
+        } = {}
+    ): Promise<T> {
+        const {
+            maxRetries = 3,
+            delay = 1000,
+            exponentialBackoff = true,
+            retryCondition = () => true
+        } = options
+
+        let lastError: Error
+        
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn()
+            } catch (error) {
+                lastError = error as Error
+                
+                // 如果是最后一次尝试或不满足重试条件，直接抛出错误
+                if (attempt === maxRetries || !retryCondition(lastError)) {
+                    throw lastError
+                }
+                
+                // 计算延迟时间
+                const currentDelay = exponentialBackoff 
+                    ? delay * Math.pow(2, attempt)
+                    : delay
+                
+                // 等待后重试
+                await new Promise(resolve => setTimeout(resolve, currentDelay))
+            }
+        }
+        
+        throw lastError!
+    }
+}
+
+/**
+ * 断路器模式实现
+ */
+export class CircuitBreaker {
+    private failures: number = 0
+    private lastFailureTime: number = 0
+    private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED'
+
+    constructor(
+        private failureThreshold: number = 5,
+        private timeoutMs: number = 60000,
+        private monitoringPeriodMs: number = 10000
+    ) {}
+
+    /**
+     * 执行受保护的操作
+     */
+    async execute<T>(fn: () => Promise<T>): Promise<T> {
+        if (this.state === 'OPEN') {
+            if (Date.now() - this.lastFailureTime > this.timeoutMs) {
+                this.state = 'HALF_OPEN'
+            } else {
+                throw new Error('Circuit breaker is OPEN')
+            }
+        }
+
+        try {
+            const result = await fn()
+            this.onSuccess()
+            return result
+        } catch (error) {
+            this.onFailure()
+            throw error
+        }
+    }
+
+    private onSuccess(): void {
+        this.failures = 0
+        this.state = 'CLOSED'
+    }
+
+    private onFailure(): void {
+        this.failures++
+        this.lastFailureTime = Date.now()
+        
+        if (this.failures >= this.failureThreshold) {
+            this.state = 'OPEN'
+        }
+    }
+
+    /**
+     * 获取断路器状态
+     */
+    getState(): 'CLOSED' | 'OPEN' | 'HALF_OPEN' {
+        return this.state
+    }
+
+    /**
+     * 重置断路器
+     */
+    reset(): void {
+        this.failures = 0
+        this.lastFailureTime = 0
+        this.state = 'CLOSED'
+    }
+}
+
+// 默认错误管理器实例
+export const errorManager = new ErrorManager()
+
+// 默认错误处理器
+errorManager.registerGlobal((error, context) => {
+    // Default error handler - logs to console
+})

package/src/index.ts

@@ -1,14 +1,17 @@
-// ============================================================================
-// Zhin Bot Framework - HMR Edition
-// ============================================================================
-
-// 核心系统
-export type { Bot } from './bot.js';
-export { loadConfig, saveConfig, createDefaultConfig } from './config.js';
-export * from './types.js';
-export * from './config.js';
+// Core exports
+export * from './app.js'
+export * from './bot.js'
+export * from './plugin.js'
+export * from './command.js'
+export * from './component.js'
 export * from './adapter.js'
-export * from './plugin.js';
-// HMR Bot系统 (主要API)
-export * from './app.js';
-export * from '@zhin.js/hmr';
+export * from './config.js'
+export * from './message.js'
+// Logger moved to @zhin.js/logger package
+export * from './types.js'
+export * from './utils.js'
+export * from './errors.js'  // 导出错误处理系统
+export * from './cron.js'
+export * from '@zhin.js/database'
+
+export { Dependency } from '@zhin.js/hmr'

package/src/jsx-runtime.ts

@@ -0,0 +1,12 @@
+// JSX 运行时入口文件
+import { jsx, jsxs, Fragment, renderJSX } from './jsx.js';
+
+export { jsx, jsxs, Fragment, renderJSX };
+
+// 默认导出 JSX 运行时
+export default {
+    jsx,
+    jsxs,
+    Fragment,
+    renderJSX
+};

package/src/jsx.d.ts

@@ -0,0 +1,52 @@
+import { SendContent } from './types.js';
+import { Component,ComponentContext } from './component.js';
+import { MessageElement } from './types.js';
+
+declare global {
+    namespace JSX {
+        interface Element {
+            type: string | Component<any>;
+            data: Record<string, any>;
+            children?: JSXChildren;
+        }
+
+        interface ElementClass {
+            render(props: any, context?: ComponentContext): MaybePromise<SendContent>;
+        }
+
+        interface ElementAttributesProperty {
+            data: {};
+        }
+
+        interface ElementChildrenAttribute {
+            children: {};
+        }
+
+        interface IntrinsicElements {
+            // 简化的组件元素
+            fetch: JSXFetchElement;
+        }
+    }
+}
+
+// 简化的组件属性接口
+interface JSXBaseElement {
+    children?: JSXChildren;
+}
+
+interface JSXFetchElement extends JSXBaseElement {
+    url?: string;
+}
+
+// JSX 子元素类型
+type JSXChildren = MessageElement | string | number | boolean | null | undefined | JSXChildren[];
+
+// JSX 元素类型
+type JSXElement = {
+    type: string | Component<any>;
+    data: Record<string, any>;
+    children?: JSXChildren;
+};
+
+// 类型辅助
+type MaybePromise<T> = T | Promise<T>;