@taicode/common-base 3.0.1 → 3.1.0

package/output/ring-cache/ring-cache.test.js

@@ -2,7 +2,7 @@
  * RingCache 测试文件
  */
 import { describe, it, expect, beforeEach } from 'vitest';
-import { RingCache } from './ring-cache';
+import { RingCache } from './ring-cache.js';
 describe('RingCache', () => {
     let cache;
     beforeEach(() => {

package/output/scheduler/index.d.ts

@@ -0,0 +1,2 @@
+export * from './scheduler';
+//# sourceMappingURL=index.d.ts.map

package/output/scheduler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/scheduler/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/output/scheduler/index.js

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

package/output/scheduler/scheduler.d.ts

@@ -0,0 +1,222 @@
+import { EventEmitter } from '../event-emitter';
+import { type CatchResult } from '../catch';
+/**
+ * 定时任务配置
+ */
+export interface ScheduledTaskConfig {
+    /**
+     * 任务唯一标识
+     */
+    id: string;
+    /**
+     * 任务执行间隔（秒），必须是 10 的倍数
+     */
+    interval: number;
+    /**
+     * 任务处理函数
+     */
+    handler: () => Promise<void> | void;
+    /**
+     * 最大重试次数，默认 3
+     */
+    maxRetries?: number;
+    /**
+     * 重试间隔（毫秒），默认 1000
+     */
+    retryDelay?: number;
+    /**
+     * 是否在启动时立即执行一次，默认 false
+     */
+    immediate?: boolean;
+    /**
+     * 是否启用，默认 true
+     */
+    enabled?: boolean;
+}
+/**
+ * 任务执行记录
+ */
+export interface TaskExecution {
+    taskId: string;
+    startTime: number;
+    endTime?: number;
+    success: boolean;
+    error?: Error;
+    retryCount: number;
+}
+/**
+ * 调度器事件
+ */
+export interface SchedulerEvents {
+    'task:start': {
+        taskId: string;
+    };
+    'task:success': {
+        taskId: string;
+        duration: number;
+    };
+    'task:error': {
+        taskId: string;
+        error: Error;
+        retryCount: number;
+    };
+    'task:retry': {
+        taskId: string;
+        retryCount: number;
+        maxRetries: number;
+    };
+    'task:failed': {
+        taskId: string;
+        error: Error;
+    };
+    'scheduler:start': void;
+    'scheduler:stop': void;
+    'scheduler:tick': {
+        tick: number;
+    };
+}
+/**
+ * 内部任务状态
+ */
+interface TaskState {
+    config: Required<ScheduledTaskConfig>;
+    nextTick: number;
+    running: boolean;
+    retryCount: number;
+    lastError?: Error;
+    executions: TaskExecution[];
+}
+/**
+ * 定时任务调度器
+ *
+ * 以 10 秒为基本时间单位，支持多个不同间隔的定时任务
+ *
+ * @example
+ * ```ts
+ * const scheduler = new Scheduler()
+ *
+ * // 添加每 30 秒执行一次的任务
+ * scheduler.addTask({
+ *   id: 'sync-data',
+ *   interval: 30,
+ *   handler: async () => {
+ *     await syncDataToServer()
+ *   },
+ *   maxRetries: 3
+ * })
+ *
+ * // 添加每 60 秒执行一次的任务
+ * scheduler.addTask({
+ *   id: 'cleanup',
+ *   interval: 60,
+ *   handler: async () => {
+ *     await cleanupTempFiles()
+ *   }
+ * })
+ *
+ * // 启动调度器
+ * scheduler.start()
+ *
+ * // 监听事件
+ * scheduler.on('task:error', (taskId, error) => {
+ *   console.error(`Task ${taskId} failed:`, error)
+ * })
+ *
+ * // 停止调度器
+ * scheduler.stop()
+ * ```
+ */
+export declare class Scheduler extends EventEmitter<SchedulerEvents> {
+    /**
+     * 基本时间单位（秒）
+     */
+    private static readonly TICK_INTERVAL;
+    /**
+     * 当前 tick 计数
+     */
+    private currentTick;
+    /**
+     * 定时器 ID
+     */
+    private timerId;
+    /**
+     * 是否正在运行
+     */
+    private running;
+    /**
+     * 任务状态映射
+     */
+    private tasks;
+    /**
+     * 添加定时任务
+     */
+    addTask(config: ScheduledTaskConfig): void;
+    /**
+     * 移除定时任务
+     */
+    removeTask(taskId: string): boolean;
+    /**
+     * 启用任务
+     */
+    enableTask(taskId: string): boolean;
+    /**
+     * 禁用任务
+     */
+    disableTask(taskId: string): boolean;
+    /**
+     * 获取任务状态
+     */
+    getTaskState(taskId: string): Readonly<TaskState> | undefined;
+    /**
+     * 获取所有任务 ID
+     */
+    getTaskIds(): string[];
+    /**
+     * 启动调度器
+     */
+    start(): void;
+    /**
+     * 停止调度器
+     */
+    stop(): void;
+    /**
+     * 是否正在运行
+     */
+    isRunning(): boolean;
+    /**
+     * 获取当前 tick
+     */
+    getCurrentTick(): number;
+    /**
+     * 手动触发任务执行（忽略时间间隔）
+     */
+    triggerTask(taskId: string): Promise<CatchResult<void, string>>;
+    /**
+     * 执行 tick
+     */
+    private tick;
+    /**
+     * 执行任务
+     */
+    private executeTask;
+    /**
+     * 获取任务执行历史
+     */
+    getTaskExecutions(taskId: string, limit?: number): TaskExecution[];
+    /**
+     * 获取调度器统计信息
+     */
+    getStats(): {
+        running: boolean;
+        currentTick: number;
+        totalTasks: number;
+        enabledTasks: number;
+        runningTasks: number;
+    };
+    /**
+     * 清理所有任务
+     */
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=scheduler.d.ts.map

package/output/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../source/scheduler/scheduler.ts"],"names":[],"mappings":"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"}

package/output/scheduler/scheduler.js

@@ -0,0 +1,348 @@
+import { EventEmitter } from '../event-emitter';
+import { catchIt } from '../catch';
+/**
+ * 定时任务调度器
+ *
+ * 以 10 秒为基本时间单位，支持多个不同间隔的定时任务
+ *
+ * @example
+ * ```ts
+ * const scheduler = new Scheduler()
+ *
+ * // 添加每 30 秒执行一次的任务
+ * scheduler.addTask({
+ *   id: 'sync-data',
+ *   interval: 30,
+ *   handler: async () => {
+ *     await syncDataToServer()
+ *   },
+ *   maxRetries: 3
+ * })
+ *
+ * // 添加每 60 秒执行一次的任务
+ * scheduler.addTask({
+ *   id: 'cleanup',
+ *   interval: 60,
+ *   handler: async () => {
+ *     await cleanupTempFiles()
+ *   }
+ * })
+ *
+ * // 启动调度器
+ * scheduler.start()
+ *
+ * // 监听事件
+ * scheduler.on('task:error', (taskId, error) => {
+ *   console.error(`Task ${taskId} failed:`, error)
+ * })
+ *
+ * // 停止调度器
+ * scheduler.stop()
+ * ```
+ */
+export class Scheduler extends EventEmitter {
+    /**
+     * 基本时间单位（秒）
+     */
+    static TICK_INTERVAL = 10;
+    /**
+     * 当前 tick 计数
+     */
+    currentTick = 0;
+    /**
+     * 定时器 ID
+     */
+    timerId = null;
+    /**
+     * 是否正在运行
+     */
+    running = false;
+    /**
+     * 任务状态映射
+     */
+    tasks = new Map();
+    /**
+     * 添加定时任务
+     */
+    addTask(config) {
+        // 验证参数
+        if (!config.id) {
+            throw new Error('[Scheduler] Task id is required');
+        }
+        if (!config.interval || config.interval <= 0) {
+            throw new Error('[Scheduler] Task interval must be positive');
+        }
+        if (config.interval % Scheduler.TICK_INTERVAL !== 0) {
+            throw new Error(`[Scheduler] Task interval must be a multiple of ${Scheduler.TICK_INTERVAL} seconds`);
+        }
+        if (!config.handler) {
+            throw new Error('[Scheduler] Task handler is required');
+        }
+        if (this.tasks.has(config.id)) {
+            throw new Error(`[Scheduler] Task with id "${config.id}" already exists`);
+        }
+        // 创建任务状态
+        const taskState = {
+            config: {
+                id: config.id,
+                interval: config.interval,
+                handler: config.handler,
+                maxRetries: config.maxRetries ?? 3,
+                retryDelay: config.retryDelay ?? 1000,
+                immediate: config.immediate ?? false,
+                enabled: config.enabled ?? true,
+            },
+            nextTick: config.immediate ? 0 : Math.ceil(config.interval / Scheduler.TICK_INTERVAL),
+            running: false,
+            retryCount: 0,
+            executions: [],
+        };
+        this.tasks.set(config.id, taskState);
+        console.log(`[Scheduler] Task "${config.id}" added (interval: ${config.interval}s)`);
+    }
+    /**
+     * 移除定时任务
+     */
+    removeTask(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return false;
+        }
+        if (task.running) {
+            console.warn(`[Scheduler] Cannot remove running task "${taskId}"`);
+            return false;
+        }
+        this.tasks.delete(taskId);
+        console.log(`[Scheduler] Task "${taskId}" removed`);
+        return true;
+    }
+    /**
+     * 启用任务
+     */
+    enableTask(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return false;
+        }
+        task.config.enabled = true;
+        console.log(`[Scheduler] Task "${taskId}" enabled`);
+        return true;
+    }
+    /**
+     * 禁用任务
+     */
+    disableTask(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return false;
+        }
+        task.config.enabled = false;
+        console.log(`[Scheduler] Task "${taskId}" disabled`);
+        return true;
+    }
+    /**
+     * 获取任务状态
+     */
+    getTaskState(taskId) {
+        const task = this.tasks.get(taskId);
+        return task ? { ...task } : undefined;
+    }
+    /**
+     * 获取所有任务 ID
+     */
+    getTaskIds() {
+        return Array.from(this.tasks.keys());
+    }
+    /**
+     * 启动调度器
+     */
+    start() {
+        if (this.running) {
+            console.warn('[Scheduler] Scheduler is already running');
+            return;
+        }
+        this.running = true;
+        this.currentTick = 0;
+        this.emit('scheduler:start', undefined);
+        console.log('[Scheduler] Scheduler started');
+        // 立即执行一次 tick
+        this.tick();
+        // 设置定时器
+        this.timerId = setInterval(() => {
+            this.tick();
+        }, Scheduler.TICK_INTERVAL * 1000);
+    }
+    /**
+     * 停止调度器
+     */
+    stop() {
+        if (!this.running) {
+            return;
+        }
+        if (this.timerId) {
+            clearInterval(this.timerId);
+            this.timerId = null;
+        }
+        this.running = false;
+        this.emit('scheduler:stop', undefined);
+        console.log('[Scheduler] Scheduler stopped');
+    }
+    /**
+     * 是否正在运行
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * 获取当前 tick
+     */
+    getCurrentTick() {
+        return this.currentTick;
+    }
+    /**
+     * 手动触发任务执行（忽略时间间隔）
+     */
+    async triggerTask(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return catchIt(async () => {
+                throw new Error(`Task "${taskId}" not found`);
+            });
+        }
+        return this.executeTask(task);
+    }
+    /**
+     * 执行 tick
+     */
+    tick() {
+        this.currentTick++;
+        this.emit('scheduler:tick', { tick: this.currentTick });
+        // 检查需要执行的任务
+        for (const task of this.tasks.values()) {
+            if (!task.config.enabled) {
+                continue;
+            }
+            if (task.running) {
+                continue;
+            }
+            // 检查是否到达执行时间
+            if (this.currentTick >= task.nextTick) {
+                // 异步执行任务，不阻塞 tick
+                this.executeTask(task).catch((error) => {
+                    console.error(`[Scheduler] Unexpected error in task "${task.config.id}":`, error);
+                });
+            }
+        }
+    }
+    /**
+     * 执行任务
+     */
+    async executeTask(task) {
+        const { config } = task;
+        const startTime = Date.now();
+        task.running = true;
+        this.emit('task:start', { taskId: config.id });
+        const execution = {
+            taskId: config.id,
+            startTime,
+            success: false,
+            retryCount: task.retryCount,
+        };
+        const result = await catchIt(async () => config.handler());
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+        execution.endTime = endTime;
+        if (result.isError()) {
+            // 执行失败
+            const error = new Error(String(result.error));
+            execution.success = false;
+            execution.error = error;
+            task.lastError = error;
+            task.retryCount++;
+            this.emit('task:error', { taskId: config.id, error, retryCount: task.retryCount });
+            // 检查是否需要重试
+            if (task.retryCount <= config.maxRetries) {
+                this.emit('task:retry', {
+                    taskId: config.id,
+                    retryCount: task.retryCount,
+                    maxRetries: config.maxRetries,
+                });
+                console.warn(`[Scheduler] Task "${config.id}" failed, will retry (${task.retryCount}/${config.maxRetries})`);
+                // 延迟后重试
+                await new Promise((resolve) => setTimeout(resolve, config.retryDelay));
+                task.running = false;
+                return this.executeTask(task);
+            }
+            else {
+                // 超过最大重试次数
+                this.emit('task:failed', { taskId: config.id, error });
+                console.error(`[Scheduler] Task "${config.id}" failed after ${config.maxRetries} retries:`, error.message);
+                // 重置重试计数，计划下次执行
+                task.retryCount = 0;
+                task.nextTick = this.currentTick + Math.ceil(config.interval / Scheduler.TICK_INTERVAL);
+                task.running = false;
+                task.executions.push(execution);
+                return result;
+            }
+        }
+        else {
+            // 执行成功
+            execution.success = true;
+            task.retryCount = 0;
+            task.lastError = undefined;
+            this.emit('task:success', { taskId: config.id, duration });
+            // 计划下次执行
+            task.nextTick = this.currentTick + Math.ceil(config.interval / Scheduler.TICK_INTERVAL);
+            task.running = false;
+            task.executions.push(execution);
+            // 保留最近 100 条执行记录
+            if (task.executions.length > 100) {
+                task.executions = task.executions.slice(-100);
+            }
+            return result;
+        }
+    }
+    /**
+     * 获取任务执行历史
+     */
+    getTaskExecutions(taskId, limit = 10) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return [];
+        }
+        return task.executions.slice(-limit);
+    }
+    /**
+     * 获取调度器统计信息
+     */
+    getStats() {
+        let enabledTasks = 0;
+        let runningTasks = 0;
+        for (const task of this.tasks.values()) {
+            if (task.config.enabled) {
+                enabledTasks++;
+            }
+            if (task.running) {
+                runningTasks++;
+            }
+        }
+        return {
+            running: this.running,
+            currentTick: this.currentTick,
+            totalTasks: this.tasks.size,
+            enabledTasks,
+            runningTasks,
+        };
+    }
+    /**
+     * 清理所有任务
+     */
+    clear() {
+        if (this.running) {
+            console.warn('[Scheduler] Cannot clear tasks while scheduler is running');
+            return;
+        }
+        this.tasks.clear();
+        console.log('[Scheduler] All tasks cleared');
+    }
+}

package/output/scheduler/scheduler.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scheduler.test.d.ts.map

package/output/scheduler/scheduler.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.test.d.ts","sourceRoot":"","sources":["../../source/scheduler/scheduler.test.ts"],"names":[],"mappings":""}