hyper-scheduler 1.0.0

package/docs/guide/core-concepts.md

@@ -0,0 +1,363 @@
+# 核心概念
+
+## 调度器 (Scheduler)
+
+调度器是系统的核心控制器，负责：
+
+- 任务注册与管理
+- 时间循环维护
+- 任务触发与执行
+- 状态跟踪
+
+### 生命周期
+
+```typescript
+const scheduler = new Scheduler();
+
+// 注册任务
+scheduler.createTask({ ... });
+
+// 启动调度
+scheduler.start();
+
+// 停止调度
+scheduler.stop();
+```
+
+### 配置项
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `debug` | `boolean` | `false` | 启用调试日志 |
+| `timezone` | `string` | 系统时区 | 全局时区 |
+| `maxHistory` | `number` | `50` | 历史记录上限 |
+| `driver` | `'worker' \| 'main'` | `'worker'` | 定时器驱动方式（仅浏览器） |
+
+### 定时器驱动方式
+
+在浏览器环境中，Hyper Scheduler 支持两种定时器驱动方式：
+
+**Worker 驱动（默认）**
+
+使用 Web Worker 在后台线程运行定时器：
+- ✅ 不受浏览器后台标签页节流限制
+- ✅ 定时更精确
+- ✅ 不阻塞主线程
+
+**主线程驱动**
+
+使用原生 `setTimeout` 在主线程运行定时器：
+- ✅ 实现更简单
+- ✅ 调试更方便
+- ⚠️ 后台标签页可能受节流影响
+
+#### 全局配置
+
+```typescript
+// 所有任务默认使用 Worker 驱动
+const scheduler = new Scheduler({ 
+  driver: 'worker' // 默认值，可省略
+});
+
+// 所有任务默认使用主线程驱动
+const scheduler = new Scheduler({ 
+  driver: 'main' 
+});
+```
+
+#### 任务级配置
+
+可以为单个任务指定不同的驱动方式，覆盖全局配置：
+
+```typescript
+const scheduler = new Scheduler({ driver: 'worker' });
+
+// 这个任务使用主线程驱动（覆盖全局配置）
+scheduler.createTask({
+  id: 'simple-task',
+  schedule: '5s',
+  handler: () => console.log('Hello'),
+  options: {
+    driver: 'main'
+  }
+});
+
+// 这个任务使用 Worker 驱动（继承全局配置）
+scheduler.createTask({
+  id: 'precise-task',
+  schedule: '1s',
+  handler: () => console.log('Precise!')
+});
+```
+
+> **注意**：Node.js 环境始终使用主线程 `setTimeout`，`driver` 配置无效。
+
+---
+
+## 任务 (Task)
+
+任务是调度的基本单元，包含三个核心要素：
+
+### ID
+
+任务的唯一标识符，用于查询、触发、停止等操作。
+
+### Schedule
+
+调度规则，支持两种格式：
+
+**Cron 表达式**
+
+```
+秒 分 时 日 月 周
+```
+
+| 字段 | 取值范围 | 特殊字符 |
+|------|----------|----------|
+| 秒 | 0-59 | `*` `,` `-` `/` |
+| 分 | 0-59 | `*` `,` `-` `/` |
+| 时 | 0-23 | `*` `,` `-` `/` |
+| 日 | 1-31 | `*` `,` `-` `/` |
+| 月 | 1-12 | `*` `,` `-` `/` |
+| 周 | 0-7 | `*` `,` `-` `/` |
+
+特殊字符说明：
+- `*` - 任意值
+- `,` - 列举值，如 `1,3,5`
+- `-` - 范围，如 `1-5`
+- `/` - 步长，如 `*/5`
+
+**时间间隔**
+
+| 单位 | 示例 |
+|------|------|
+| `s` | `30s` - 每 30 秒 |
+| `m` | `5m` - 每 5 分钟 |
+| `h` | `2h` - 每 2 小时 |
+| `d` | `1d` - 每天 |
+
+### Handler
+
+任务执行函数，支持同步和异步：
+
+```typescript
+// 同步
+handler: () => {
+  console.log('executed');
+}
+
+// 异步
+handler: async () => {
+  await fetchData();
+}
+```
+
+---
+
+## 任务状态
+
+| 状态 | 说明 |
+|------|------|
+| `stopped` | 已停止，不参与调度 |
+| `idle` | 等待调度，将在下次触发时间执行 |
+| `running` | 正在执行 |
+| `error` | 执行出错 |
+
+状态流转：
+
+```
+stopped -> idle -> running -> idle
+                      |
+                      v
+                    error -> idle (重试) 或 error (放弃)
+```
+
+---
+
+## 任务选项
+
+### 重试配置
+
+任务执行失败时可自动重试：
+
+```typescript
+scheduler.createTask({
+  id: 'api-call',
+  schedule: '1m',
+  handler: async () => {
+    await callAPI();
+  },
+  options: {
+    retry: {
+      maxAttempts: 3,     // 最大重试次数
+      initialDelay: 1000, // 首次重试延迟 (ms)
+      factor: 2           // 延迟递增因子
+    }
+  }
+});
+```
+
+重试延迟计算：`initialDelay * (factor ^ attempt)`
+
+示例（initialDelay=1000, factor=2）：
+- 第 1 次重试：1000ms
+- 第 2 次重试：2000ms
+- 第 3 次重试：4000ms
+
+### 错误处理
+
+通过 `onError` 回调处理任务执行错误：
+
+```typescript
+scheduler.createTask({
+  id: 'critical-task',
+  schedule: '30s',
+  handler: async () => {
+    await criticalOperation();
+  },
+  options: {
+    onError: (error, taskId) => {
+      // 记录错误日志
+      logger.error(`Task ${taskId} failed:`, error);
+      // 发送告警
+      alertService.send({
+        title: 'Task Failed',
+        message: error.message,
+        taskId
+      });
+    }
+  }
+});
+```
+
+### 时区配置
+
+为任务指定专属时区：
+
+```typescript
+scheduler.createTask({
+  id: 'tokyo-report',
+  schedule: '0 0 9 * * *', // 每天 9:00
+  handler: () => generateReport(),
+  options: {
+    timezone: 'Asia/Tokyo'
+  }
+});
+```
+
+---
+
+## 计时策略
+
+调度器根据运行环境自动选择计时策略：
+
+### Node.js
+
+使用 `setTimeout` + `process.hrtime` 实现高精度计时。
+
+### 浏览器
+
+优先使用 Web Worker 运行计时循环，避免后台标签页节流问题。
+
+浏览器在标签页切换到后台时会限制 `setTimeout` 最小间隔为 1 秒，Web Worker 不受此限制。
+
+---
+
+## 任务标签
+
+标签用于任务分类和过滤：
+
+```typescript
+scheduler.createTask({
+  id: 'sync-orders',
+  schedule: '1m',
+  tags: ['sync', 'orders', 'critical'],
+  handler: async () => {
+    await syncOrders();
+  }
+});
+```
+
+在 DevTools 中可按标签搜索过滤任务。
+
+---
+
+## 执行历史
+
+每个任务记录最近的执行历史：
+
+```typescript
+interface ExecutionRecord {
+  timestamp: number;  // 执行时间戳
+  duration: number;   // 执行耗时 (ms)
+  success: boolean;   // 是否成功
+  error?: string;     // 错误信息
+}
+```
+
+通过 `maxHistory` 配置控制保留数量，默认 50 条。
+
+---
+
+## 事件系统
+
+调度器支持事件订阅：
+
+```typescript
+// 订阅
+const unsubscribe = scheduler.on('task_completed', (payload) => {
+  console.log(`${payload.taskId} completed`);
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+| 事件 | 触发时机 |
+|------|----------|
+| `task_registered` | 任务注册 |
+| `task_started` | 开始执行 |
+| `task_completed` | 执行成功 |
+| `task_failed` | 执行失败 |
+| `task_stopped` | 任务停止 |
+| `task_removed` | 任务删除 |
+
+---
+
+## DevTools
+
+浏览器环境下的可视化调试工具。
+
+### 配置项
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | 主题模式 |
+| `dockPosition` | `'right' \| 'bottom'` | `'right'` | 面板停靠位置 |
+| `language` | `'en' \| 'zh'` | `'en'` | 界面语言 |
+| `defaultZoom` | `number` | `1` | 时间线缩放级别 (0.5-5) |
+| `trigger.backgroundColor` | `string` | `'#3b82f6'` | 悬浮按钮背景色 |
+| `trigger.textColor` | `string` | `'#ffffff'` | 悬浮按钮文字颜色 |
+| `trigger.position` | `string` | `'bottom-right'` | 悬浮按钮位置 |
+
+### 示例
+
+```typescript
+import { Scheduler, DevTools } from 'hyper-scheduler';
+
+const scheduler = new Scheduler({
+  plugins: [
+    new DevTools({
+      theme: 'dark',
+      language: 'zh',
+      dockPosition: 'bottom',
+      defaultZoom: 2,
+      trigger: {
+        backgroundColor: '#10b981',
+        textColor: '#ffffff',
+        position: 'bottom-left'
+      }
+    })
+  ]
+});
+```

package/docs/guide/getting-started.md

@@ -0,0 +1,138 @@
+# 快速开始
+
+## 安装
+
+```bash
+npm install hyper-scheduler
+# 或
+pnpm add hyper-scheduler
+# 或
+yarn add hyper-scheduler
+```
+
+## 基础用法
+
+### 1. 创建调度器
+
+```typescript
+import { Scheduler } from 'hyper-scheduler';
+
+const scheduler = new Scheduler({
+  debug: true,      // 开启调试日志
+  maxHistory: 100   // 保留最近 100 条执行记录
+});
+```
+
+### 2. 注册任务
+
+支持两种调度规则：Cron 表达式和时间间隔。
+
+```typescript
+// Cron 表达式：每分钟执行
+scheduler.createTask({
+  id: 'cron-task',
+  schedule: '0 * * * * *',
+  handler: () => {
+    console.log('Cron task executed');
+  }
+});
+
+// 时间间隔：每 5 秒执行
+scheduler.createTask({
+  id: 'interval-task',
+  schedule: '5s',
+  handler: () => {
+    console.log('Interval task executed');
+  }
+});
+```
+
+### 3. 启动调度器
+
+```typescript
+scheduler.start();
+```
+
+## 完整示例
+
+```typescript
+import { Scheduler } from 'hyper-scheduler';
+
+const scheduler = new Scheduler({ debug: true });
+
+// Cron 任务：每 3 秒
+scheduler.createTask({
+  id: 'cron-task',
+  schedule: '*/3 * * * * *',
+  handler: () => console.log('Cron task executed')
+});
+
+// 间隔任务：每 5 秒
+scheduler.createTask({
+  id: 'interval-task',
+  schedule: '5s',
+  handler: () => console.log('Interval task executed')
+});
+
+// 启动调度器
+scheduler.start();
+```
+
+## 浏览器环境
+
+在浏览器中可以启用可视化调试工具，通过在 Scheduler 构造函数中传入 DevTools 插件实现：
+
+```typescript
+import { Scheduler, DevTools } from 'hyper-scheduler';
+
+const scheduler = new Scheduler({
+  debug: true,
+  plugins: [
+    new DevTools({
+      theme: 'auto',
+      dockPosition: 'right',
+      language: 'zh',
+      defaultZoom: 1,
+      trigger: {
+        backgroundColor: '#3b82f6',
+        textColor: '#ffffff',
+        position: 'bottom-right'
+      }
+    })
+  ]
+});
+
+// 注册任务...
+
+scheduler.start();
+```
+
+## 调度规则
+
+### Cron 表达式
+
+```
+秒 分 时 日 月 周
+```
+
+| 示例 | 说明 |
+|------|------|
+| `0 * * * * *` | 每分钟 |
+| `*/5 * * * * *` | 每 5 秒 |
+| `0 0 * * * *` | 每小时 |
+| `0 0 2 * * *` | 每天凌晨 2:00 |
+| `0 0 9 * * 1` | 每周一 9:00 |
+
+### 时间间隔
+
+| 格式 | 说明 |
+|------|------|
+| `30s` | 每 30 秒 |
+| `5m` | 每 5 分钟 |
+| `2h` | 每 2 小时 |
+| `1d` | 每天 |
+
+## 下一步
+
+- [核心概念](./core-concepts.md) - 深入理解调度机制
+- [API 文档](../api/scheduler.md) - 完整 API 参考

package/docs/index.md

@@ -0,0 +1,33 @@
+---
+layout: home
+
+hero:
+  name: Hyper Scheduler
+  text: 轻量级、高性能的全局任务调度 JS 库
+  image:
+    src: /logo.svg
+    alt: Hyper Scheduler Logo
+  tagline: 支持 Cron 表达式与人性化时间间隔，浏览器与 Node.js 通用
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /guide/getting-started
+    - theme: alt
+      text: 核心概念
+      link: /guide/core-concepts
+
+features:
+  - title: 灵活调度
+    details: 同时支持标准的 Cron 表达式（如 `*/5 * * * *`）和人性化的时间间隔字符串（如 `10s`, `1h`）。
+  - title: 跨平台
+    details: 支持浏览器和 Node.js 环境，一份代码，多端运行。浏览器端自动使用 Web Worker 防止阻塞。
+  - title: 精准计时
+    details: 浏览器端通过 Web Worker 确保后台任务精准执行，即使在页面标签页后台运行时也能避免节流限制。
+  - title: 开发友好
+    details: API 设计简洁直观。内置调试工具，支持日志追踪和可视化调试（WIP）。
+  - title: 轻量级
+    details: 核心库体积小巧，模块化设计，支持 Tree-shaking。
+  - title: TypeScript
+    details: 完全使用 TypeScript 编写，提供完整的类型定义，开发体验极佳。
+
+footer: MIT Licensed | Copyright © 2025-present Hyper Scheduler Contributors

package/docs/public/logo.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" fill="none">
+  <defs>
+    <linearGradient id="main" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#6366f1"/>
+      <stop offset="100%" style="stop-color:#a855f7"/>
+    </linearGradient>
+    <linearGradient id="bolt" x1="50%" y1="0%" x2="50%" y2="100%">
+      <stop offset="0%" style="stop-color:#fcd34d"/>
+      <stop offset="100%" style="stop-color:#f59e0b"/>
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="2" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+    <filter id="softShadow">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#6366f1" flood-opacity="0.3"/>
+    </filter>
+  </defs>
+  
+  <!-- 背景圆 - 柔和填充 -->
+  <circle cx="64" cy="64" r="56" fill="url(#main)" opacity="0.1"/>
+  
+  <!-- 刻度点 - 简约时钟感 -->
+  <g fill="url(#main)" opacity="0.7">
+    <circle cx="64" cy="16" r="4"/>
+    <circle cx="112" cy="64" r="4"/>
+    <circle cx="64" cy="112" r="4"/>
+    <circle cx="16" cy="64" r="4"/>
+  </g>
+  
+  <!-- 次要刻度 -->
+  <g fill="url(#main)" opacity="0.35">
+    <circle cx="98" cy="26" r="2.5"/>
+    <circle cx="102" cy="98" r="2.5"/>
+    <circle cx="26" cy="98" r="2.5"/>
+    <circle cx="30" cy="26" r="2.5"/>
+  </g>
+  
+  <!-- 闪电 - 核心元素 -->
+  <path d="M72 20 L44 68 L62 68 L52 108 L88 52 L68 52 L72 20Z" 
+        fill="url(#bolt)" 
+        filter="url(#glow)"/>
+  
+  <!-- 闪电高光 -->
+  <path d="M70 26 L50 64 L62 64 L56 92" 
+        stroke="#fff" 
+        stroke-width="2" 
+        stroke-linecap="round"
+        fill="none"
+        opacity="0.4"/>
+</svg>