hyper-scheduler 1.0.0

package/src/index.ts

@@ -0,0 +1,74 @@
+import { Scheduler as CoreScheduler, TimerStrategyFactory } from './core/scheduler';
+import { SchedulerConfig } from './types';
+import { NodeTimer } from './platform/node/node-timer';
+import { BrowserTimer } from './platform/browser/browser-timer';
+import { MainThreadTimer } from './platform/browser/main-thread-timer';
+import { TimerStrategy } from './platform/timer-strategy';
+import { DevTools } from './plugins/dev-tools';
+import { TaskStatus, SchedulerEvents } from './constants';
+
+// Determine environment
+const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
+// 缓存定时器策略实例
+let workerTimerInstance: BrowserTimer | null = null;
+let mainTimerInstance: MainThreadTimer | null = null;
+
+/**
+ * 获取默认的定时器策略
+ */
+function getDefaultTimerStrategy(config?: SchedulerConfig): TimerStrategy {
+  if (isBrowser) {
+    const driver = config?.driver || 'worker';
+    if (driver === 'main') {
+      if (!mainTimerInstance) mainTimerInstance = new MainThreadTimer();
+      return mainTimerInstance;
+    }
+    if (!workerTimerInstance) workerTimerInstance = new BrowserTimer();
+    return workerTimerInstance;
+  }
+  return new NodeTimer();
+}
+
+/**
+ * 创建定时器策略工厂（仅浏览器环境有效）
+ */
+function createTimerStrategyFactory(): TimerStrategyFactory | undefined {
+  if (!isBrowser) return undefined;
+  
+  return (driver: 'worker' | 'main'): TimerStrategy => {
+    if (driver === 'main') {
+      if (!mainTimerInstance) mainTimerInstance = new MainThreadTimer();
+      return mainTimerInstance;
+    }
+    if (!workerTimerInstance) workerTimerInstance = new BrowserTimer();
+    return workerTimerInstance;
+  };
+}
+
+/**
+ * Hyper Scheduler 主入口类。
+ * 自动根据运行环境（浏览器或 Node.js）选择合适的计时策略。
+ * 
+ * 支持两级 driver 配置：
+ * 1. 全局配置：new Scheduler({ driver: 'worker' | 'main' })
+ * 2. 任务级配置：createTask({ options: { driver: 'worker' | 'main' } })
+ * 
+ * 任务级配置优先于全局配置。
+ */
+export class Scheduler extends CoreScheduler {
+  /**
+   * 创建调度器实例。
+   * @param config 配置项
+   */
+  constructor(config?: SchedulerConfig) {
+    super(
+      getDefaultTimerStrategy(config), 
+      config,
+      createTimerStrategyFactory()
+    );
+  }
+}
+
+export * from './types';
+export { CoreScheduler, DevTools, TaskStatus, SchedulerEvents };

package/src/platform/browser/browser-timer.ts

@@ -0,0 +1,66 @@
+import { TimerStrategy } from '../timer-strategy';
+// Import the worker as a URL or constructor depending on Vite config.
+// For library mode, it is often safer to inline or assume a specific loading strategy.
+// Here we use Vite's worker import query.
+import Worker from './worker?worker&inline';
+
+/**
+ * 浏览器环境下的计时策略实现。
+ * 使用 Web Worker 来运行计时循环，以避免后台标签页的节流限制。
+ */
+export class BrowserTimer implements TimerStrategy {
+  private worker: Worker;
+  private callbacks: Map<number, () => void>;
+  private nextId: number;
+
+  constructor() {
+    // Fallback for environments without Worker (like JSDOM during tests if not mocked)
+    // In a real browser, Worker should exist.
+    if (typeof Worker !== 'undefined') {
+        this.worker = new Worker();
+    } else {
+        // Minimal mock for SSR/Test env if not provided
+        this.worker = {
+            postMessage: () => {},
+            onmessage: null,
+            terminate: () => {},
+            addEventListener: () => {},
+            removeEventListener: () => {},
+            dispatchEvent: () => false
+        } as unknown as Worker;
+    }
+
+    this.callbacks = new Map();
+    this.nextId = 1;
+
+    this.worker.onmessage = (e: MessageEvent) => {
+      const { id, type } = e.data;
+      if (type === 'tick') {
+        const callback = this.callbacks.get(id);
+        if (callback) {
+          callback();
+          this.callbacks.delete(id);
+        }
+      }
+    };
+  }
+
+  /**
+   * 安排一个定时任务。
+   * 向 Web Worker 发送消息以注册计时器。
+   */
+  schedule(callback: () => void, delay: number): number {
+    const id = this.nextId++;
+    this.callbacks.set(id, callback);
+    this.worker.postMessage({ id, delay, type: 'schedule' });
+    return id;
+  }
+
+  /**
+   * 取消一个定时任务。
+   */
+  cancel(handle: number): void {
+    this.worker.postMessage({ id: handle, type: 'cancel' });
+    this.callbacks.delete(handle);
+  }
+}

package/src/platform/browser/main-thread-timer.ts

@@ -0,0 +1,16 @@
+import { TimerStrategy } from '../timer-strategy';
+
+/**
+ * 浏览器环境下的主线程计时策略实现。
+ * 使用原生的 setTimeout/clearTimeout，运行在主线程上。
+ * 注意：在后台标签页中可能受到浏览器节流限制。
+ */
+export class MainThreadTimer implements TimerStrategy {
+  schedule(callback: () => void, delay: number): number {
+    return window.setTimeout(callback, delay) as unknown as number;
+  }
+
+  cancel(handle: number): void {
+    window.clearTimeout(handle);
+  }
+}

package/src/platform/browser/worker.ts

@@ -0,0 +1,31 @@
+/* eslint-disable no-restricted-globals */
+/**
+ * Web Worker 脚本。
+ * 用于在后台线程中运行计时器，避免主线程阻塞或页面后台节流影响计时精度。
+ */
+
+interface TimerMessage {
+  id: number;
+  delay: number;
+  type: 'schedule' | 'cancel';
+}
+
+const timers = new Map<number, number>();
+
+self.onmessage = (e: MessageEvent<TimerMessage>) => {
+  const { id, delay, type } = e.data;
+
+  if (type === 'schedule') {
+    const timerId = self.setTimeout(() => {
+      self.postMessage({ id, type: 'tick' });
+      timers.delete(id);
+    }, delay);
+    timers.set(id, timerId);
+  } else if (type === 'cancel') {
+    const timerId = timers.get(id);
+    if (timerId !== undefined) {
+      self.clearTimeout(timerId);
+      timers.delete(id);
+    }
+  }
+};

package/src/platform/node/debug-cli.ts

@@ -0,0 +1,19 @@
+import { Task } from '../../types';
+
+/**
+ * Node.js 环境下的调试 CLI 工具。
+ * 用于在控制台输出任务状态表格。
+ */
+export class DebugCLI {
+  static logTaskUpdate(tasks: Task[]): void {
+    console.clear();
+    console.log('--- Hyper Scheduler Status ---');
+    console.table(tasks.map(t => ({
+      ID: t.id,
+      Status: t.status,
+      Schedule: t.schedule,
+      NextRun: t.nextRun ? new Date(t.nextRun).toISOString() : 'N/A',
+      LastRun: t.lastRun ? new Date(t.lastRun).toISOString() : 'N/A'
+    })));
+  }
+}

package/src/platform/node/node-timer.ts

@@ -0,0 +1,15 @@
+import { TimerStrategy } from '../timer-strategy';
+
+/**
+ * Node.js 环境下的计时策略实现。
+ * 简单包装了原生的 setTimeout 和 clearTimeout。
+ */
+export class NodeTimer implements TimerStrategy {
+  schedule(callback: () => void, delay: number): NodeJS.Timeout {
+    return setTimeout(callback, delay);
+  }
+
+  cancel(handle: NodeJS.Timeout): void {
+    clearTimeout(handle);
+  }
+}

package/src/platform/timer-strategy.ts

@@ -0,0 +1,19 @@
+/**
+ * 计时策略接口。
+ * 定义了跨平台计时器（Node.js 和 浏览器）的统一接口。
+ */
+export interface TimerStrategy {
+  /**
+   * 安排一个回调函数在指定延迟后执行。
+   * @param callback 回调函数
+   * @param delay 延迟毫秒数
+   * @returns 用于取消定时器的句柄 (Handle)
+   */
+  schedule(callback: () => void, delay: number): any;
+
+  /**
+   * 取消一个已安排的定时器。
+   * @param handle schedule 方法返回的句柄
+   */
+  cancel(handle: any): void;
+}

package/src/plugins/dev-tools.ts

@@ -0,0 +1,101 @@
+import { Scheduler } from '../core/scheduler';
+import { DevToolsOptions, HyperSchedulerPlugin } from '../types';
+import { TaskStatus } from '../constants';
+
+export class DevTools implements HyperSchedulerPlugin {
+  name = 'DevTools';
+  private options: DevToolsOptions;
+
+  constructor(options: DevToolsOptions = {}) {
+    this.options = options;
+  }
+
+  init(scheduler: Scheduler): void {
+    if (typeof window === 'undefined' || typeof window.document === 'undefined') {
+      return;
+    }
+
+    this.mount(scheduler);
+  }
+
+  private async mount(scheduler: Scheduler): Promise<void> {
+    try {
+      // Import the UI component definition (side effect: defines <hs-devtools>)
+      await import('../ui/components/devtools');
+      
+      // Wait for custom element to be defined
+      await customElements.whenDefined('hs-devtools');
+      
+      this.setupElement(scheduler);
+    } catch (e) {
+      console.error('[DevTools] Failed to mount:', e);
+    }
+  }
+
+  private setupElement(scheduler: Scheduler): void {
+    try {
+      // Check DOM - always create new element to ensure clean state
+      let el = document.querySelector('hs-devtools') as any;
+      if (el) {
+        // Remove existing element to ensure fresh initialization
+        el.remove();
+      }
+      
+      // Create new element
+      el = document.createElement('hs-devtools');
+      
+      // IMPORTANT: Apply options BEFORE adding to DOM
+      // so that connectedCallback can read the attributes
+      const options = this.options;
+      console.log('[DevTools Plugin] options:', JSON.stringify(options));
+      if (options.theme) el.setAttribute('theme', options.theme);
+      if (options.dockPosition) el.setAttribute('dock', options.dockPosition);
+      if (options.language) el.setAttribute('language', options.language);
+      if (options.defaultZoom) el.setAttribute('default-zoom', options.defaultZoom.toString());
+      if (options.trigger) {
+        if (options.trigger.backgroundColor) el.setAttribute('trigger-bg', options.trigger.backgroundColor);
+        if (options.trigger.textColor) el.setAttribute('trigger-color', options.trigger.textColor);
+        if (options.trigger.position) el.setAttribute('trigger-position', options.trigger.position);
+      }
+      console.log('[DevTools Plugin] attributes set:', el.getAttribute('dock'), el.getAttribute('trigger-position'));
+      
+      // Add to DOM - connectedCallback will be called with attributes already set
+      document.body.appendChild(el);
+
+      // Set scheduler API adapter
+      // We need to wait for the element to upgrade if it hasn't already?
+      // import() promise resolution should mean the script is executed and custom element defined.
+      
+      if (typeof el.setScheduler === 'function') {
+        el.setScheduler({
+            getTasks: () => {
+            return scheduler.getAllTasks().map(task => ({
+                id: task.id,
+                status: task.status,
+                lastRun: task.lastRun || null,
+                nextRun: task.nextRun || null,
+                executionCount: task.executionCount || 0,
+                schedule: task.schedule,
+                tags: task.tags || [],
+                error: task.status === TaskStatus.ERROR ? 'Execution failed' : null,
+                driver: scheduler.getTaskDriver(task.id)
+            }));
+            },
+            on: (evt: string, handler: (payload: any) => void) => {
+                return scheduler.on(evt, handler);
+            },
+            isRunning: () => scheduler.isRunning(),
+            trigger: (id: string) => scheduler.triggerTask(id),
+            pause: (id: string) => scheduler.stopTask(id),
+            resume: (id: string) => scheduler.startTask(id),
+            remove: (id: string) => scheduler.deleteTask(id)
+        });
+      } else {
+          console.warn('[DevTools] hs-devtools element does not have setScheduler method.');
+      }
+
+    } catch (e) {
+      console.error('[DevTools] Failed to setup element:', e);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+import { TaskStatus as TaskStatusEnum } from './constants';
+
+export type TaskStatus = typeof TaskStatusEnum[keyof typeof TaskStatusEnum];
+
+export interface ExecutionRecord {
+  timestamp: number;
+  duration: number;
+  success: boolean;
+  error?: string;
+}
+
+export interface TaskOptions {
+  retry?: {
+    maxAttempts: number;
+    initialDelay: number;
+    factor?: number;
+  };
+  timezone?: string;
+  /** 任务执行失败时的错误处理回调 */
+  onError?: (error: Error, taskId: string) => void;
+  /**
+   * 定时器驱动方式（仅浏览器环境有效）
+   * - 'worker': 使用 Web Worker（默认，更精确，不受后台节流影响）
+   * - 'main': 使用主线程 setTimeout（更简单，但可能受后台节流影响）
+   * 如果不指定，则使用调度器全局配置
+   */
+  driver?: 'worker' | 'main';
+}
+
+export interface TaskDefinition {
+  id: string;
+  /**
+   * 任务调度规则。
+   * 支持:
+   * 1. Cron 表达式 (例如: "*\/5 * * * * *")
+   * 2. 间隔字符串 (例如: "10s", "5m", "1h")
+   */
+  schedule: string;
+  handler: () => void | Promise<void>;
+  options?: TaskOptions;
+  tags?: string[];
+}
+
+export interface Task extends TaskDefinition {
+  status: TaskStatus;
+  lastRun?: number;
+  nextRun?: number;
+  history: ExecutionRecord[];
+  tags?: string[];
+  executionCount?: number;
+}
+
+export interface SchedulerConfig {
+  debug?: boolean;
+  maxHistory?: number;
+  timezone?: string; // e.g., 'Asia/Shanghai'
+  plugins?: HyperSchedulerPlugin[];
+  /**
+   * 定时器驱动方式（仅浏览器环境有效）
+   * - 'worker': 使用 Web Worker（默认，更精确，不受后台节流影响）
+   * - 'main': 使用主线程 setTimeout（更简单，但可能受后台节流影响）
+   */
+  driver?: 'worker' | 'main';
+}
+
+export interface HyperSchedulerPlugin {
+  name: string;
+  init(scheduler: any, options?: any): void;
+}
+
+
+export interface TaskSnapshot {
+  id: string;
+  status: string;
+  lastRun: number | null;
+  nextRun: number | null;
+  executionCount: number;
+  schedule: string;
+  tags: string[];
+  error: string | null;
+  driver: 'worker' | 'main';
+}
+
+export interface DevToolsOptions {
+  /** 主题模式 */
+  theme?: 'light' | 'dark' | 'auto';
+  /** 面板停靠位置 */
+  dockPosition?: 'right' | 'bottom';
+  /** 界面语言 */
+  language?: 'en' | 'zh';
+  /** 时间线默认缩放级别 (0.5-5) */
+  defaultZoom?: number;
+  /** 悬浮按钮配置 */
+  trigger?: {
+    /** 背景色 */
+    backgroundColor?: string;
+    /** 文字/图标颜色 */
+    textColor?: string;
+    /** 位置 */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  };
+}
+
+export interface TaskControlAPI {
+  trigger(taskId: string): Promise<void>;
+  pause(taskId: string): void;
+  resume(taskId: string): void;
+  remove(taskId: string): void;
+}
+
+export interface SchedulerIntrospectionAPI {
+  getTasks(): TaskSnapshot[];
+  on(event: string, handler: (data: any) => void): () => void;
+  isRunning(): boolean;
+}