hyper-scheduler 1.0.0 → 1.1.0

package/docs/examples/index.md

@@ -2,6 +2,22 @@
 
 本示例展示了 `Hyper Scheduler` 的核心能力：**双线程任务调度**。你可以同时在主线程（Main Thread）和 Web Worker 线程中运行任务，互不干扰。
 
+## 在线演示
+
+以下示例展示了完全相同的“双线程心跳监控”逻辑在不同框架中的运行效果。你可以直接在这里交互，或点击右上角图标在新窗口打开。
+
+### Browser (原生 JS)
+
+<DemoFrame path="/examples/browser/" :devPort="3003" devPath="/examples/browser/index.html" title="examples/browser/index.html" />
+
+### Vue 3 Demo
+
+<DemoFrame path="/examples/vue-demo/" :devPort="3001" title="examples/vue-demo" />
+
+### React Demo
+
+<DemoFrame path="/examples/react-demo/" :devPort="3002" title="examples/react-demo" />
+
 ## 安装与引入
 
 ### 1. 安装
@@ -9,12 +25,12 @@
 使用你喜欢的包管理器安装 `hyper-scheduler`：
 
 ```bash
+# yarn (推荐)
+yarn add hyper-scheduler
+
 # npm
 npm install hyper-scheduler
 
-# yarn
-yarn add hyper-scheduler
-
 # pnpm
 pnpm add hyper-scheduler
 ```
@@ -107,7 +123,11 @@ const { Scheduler } = require('hyper-scheduler');
     scheduler.createTask({
       id: 'main-heartbeat',
       schedule: '3s',
-      options: { driver: 'main' },
+      options: { 
+        driver: 'main',
+        namespace: 'ui',
+        runImmediately: true
+      },
       handler: () => log('❤️ [Main] 主线程心跳检测正常', 'error')
     });
 
@@ -115,6 +135,9 @@ const { Scheduler } = require('hyper-scheduler');
     scheduler.createTask({
       id: 'worker-heartbeat',
       schedule: '5s',
+      options: {
+        namespace: 'background'
+      },
       handler: () => log('💙 [Worker] 后台线程任务执行中', 'info')
     });
 
@@ -150,7 +173,11 @@ console.log('✨ 系统就绪，等待启动指令...');
 scheduler.createTask({
   id: 'main-heartbeat',
   schedule: '3s',
-  options: { driver: 'main' },
+  options: { 
+    driver: 'main',
+    namespace: 'ui',
+    runImmediately: true
+  },
   handler: () => {
     console.log(`[${time()}] ❤️ [Main] 主线程心跳检测正常`);
   }
@@ -160,6 +187,9 @@ scheduler.createTask({
 scheduler.createTask({
   id: 'worker-heartbeat',
   schedule: '5s',
+  options: {
+    namespace: 'background'
+  },
   handler: () => {
     console.log(`[${time()}] 💙 [Worker] 后台线程任务执行中`);
   }
@@ -189,16 +219,25 @@ function App() {
     });
 
     // 2. 注册任务
+    // 主线程心跳 (明确指定 driver: 'main')
     schedulerRef.current.createTask({
       id: 'main-heartbeat',
       schedule: '3s',
-      options: { driver: 'main' }, 
+      options: { 
+        driver: 'main',
+        namespace: 'ui',
+        runImmediately: true
+      }, 
       handler: () => addLog('❤️ [Main] 主线程心跳检测正常', 'error')
     });
 
+    // Worker 线程心跳 (默认即为 Worker 驱动)
     schedulerRef.current.createTask({
       id: 'worker-heartbeat',
       schedule: '5s',
+      options: {
+        namespace: 'background'
+      },
       handler: () => addLog('💙 [Worker] 后台线程任务执行中', 'info')
     });
 
@@ -250,17 +289,25 @@ onMounted(() => {
     plugins: [new DevTools({ theme: 'auto', language: 'zh' })]
   })
   
-  // 2. 注册任务
+  // 主线程心跳 (明确指定 driver: 'main')
   scheduler.value.createTask({
     id: 'main-heartbeat',
     schedule: '3s',
-    options: { driver: 'main' },
+    options: { 
+      driver: 'main', 
+      namespace: 'ui',
+      runImmediately: true
+    },
     handler: () => addLog('❤️ [Main] 主线程心跳检测正常', 'error')
   })
 
+  // Worker 线程心跳 (默认即为 Worker 驱动)
   scheduler.value.createTask({
     id: 'worker-heartbeat',
     schedule: '5s',
+    options: {
+      namespace: 'background'
+    },
     handler: () => addLog('💙 [Worker] 后台线程任务执行中', 'info')
   })
 })

package/docs/guide/getting-started.md

@@ -78,6 +78,44 @@ scheduler.createTask({
 scheduler.start();
 ```
 
+## 进阶功能
+
+### 1. 使用命名空间
+
+可以将任务隔离到不同的命名空间中，以便进行批量管理（如启动、停止特定组的任务）。
+
+```typescript
+scheduler.createTask({
+  id: 'system-log',
+  schedule: '1m',
+  handler: () => console.log('System Log'),
+  options: { namespace: 'system' }
+});
+
+scheduler.createTask({
+  id: 'user-notification',
+  schedule: '5m',
+  handler: () => console.log('User Notification'),
+  options: { namespace: 'user' }
+});
+
+// 仅启动 system 命名空间下的任务
+scheduler.start('system');
+```
+
+### 2. 立即触发
+
+默认情况下，任务会在第一次调度时间到达时执行。如果你希望任务在调度器启动时（或创建时）立即执行一次，可以使用 `runImmediately` 选项。
+
+```typescript
+scheduler.createTask({
+  id: 'init-check',
+  schedule: '1h',
+  handler: () => console.log('Checking status...'),
+  options: { runImmediately: true }
+});
+```
+
 ## 浏览器环境
 
 在浏览器中可以启用可视化调试工具，通过在 Scheduler 构造函数中传入 DevTools 插件实现：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-scheduler",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A lightweight, dependency-free (core) JavaScript task scheduler supporting Cron expressions and Web Workers.",
   "type": "module",
   "main": "./dist/index.umd.js",
@@ -12,15 +12,23 @@
       "require": "./dist/index.cjs"
     }
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
   "scripts": {
     "dev": "vite",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "example:node": "node examples/node/simple.js",
-    "example:browser": "vite examples/browser",
-    "example:vue": "npm install --prefix examples/vue-demo && npm run dev --prefix examples/vue-demo",
-    "example:react": "npm install --prefix examples/react-demo && npm run dev --prefix examples/react-demo",
+    "example:browser": "vite serve . --port 3003",
+    "example:vue": "cd examples/vue-demo && yarn && yarn dev",
+    "example:react": "cd examples/react-demo && yarn && yarn dev",
+    "dev:all": "concurrently \"yarn docs:dev\" \"yarn example:vue\" \"yarn example:react\" \"vite examples/browser --port 3003\"",
     "build": "tsc && vite build",
+    "prepublishOnly": "yarn build",
     "test": "vitest",
     "lint": "eslint . --ext .ts"
   },
@@ -38,6 +46,7 @@
     "@typescript-eslint/eslint-plugin": "^8.48.0",
     "@typescript-eslint/parser": "^8.48.0",
     "@vitest/coverage-v8": "^4.0.14",
+    "concurrently": "^9.2.1",
     "eslint": "^8.0.0",
     "jsdom": "^27.2.0",
     "rollup-plugin-visualizer": "^6.0.5",

package/.editorconfig

@@ -1,21 +0,0 @@
-# EditorConfig is awesome: https://EditorConfig.org
-
-# top-most EditorConfig file
-root = true
-
-# Unix-style newlines with a newline ending every file
-[*]
-end_of_line = lf
-insert_final_newline = true
-charset = utf-8
-
-# TypeScript files
-[*.ts]
-indent_style = space
-indent_size = 2
-trim_trailing_whitespace = true
-
-# Disable auto-fix for critical UI components
-[src/ui/components/{Timeline,TaskList,DevTools}.ts]
-# These files have specific logic that should not be auto-fixed
-# Manual review required for any changes

package/.eslintrc.cjs

@@ -1,26 +0,0 @@
-module.exports = {
-  root: true,
-  env: {
-    browser: true,
-    es2021: true,
-    node: true,
-  },
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-  ],
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaVersion: 12,
-    sourceType: 'module',
-  },
-  plugins: [
-    '@typescript-eslint',
-  ],
-  rules: {
-    '@typescript-eslint/no-explicit-any': 'off',
-    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-    'no-console': 'off',
-  },
-  ignorePatterns: ['dist/', 'coverage/', 'examples/'],
-};

package/GEMINI.md

@@ -1 +0,0 @@
-全部采用中文作为主要语言进行输出，包括文档和注释

package/examples/browser/index.html

@@ -1,354 +0,0 @@
-<!DOCTYPE html>
-<html lang="zh-CN">
-
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Hyper Scheduler - 浏览器示例</title>
-  <style>
-    :root {
-      --bg-color: #f8fafc;
-      --card-bg: #ffffff;
-      --text-primary: #1e293b;
-      --text-secondary: #64748b;
-      --accent-color: #3b82f6;
-      --accent-hover: #2563eb;
-      --danger-color: #ef4444;
-      --danger-hover: #dc2626;
-      --success-color: #10b981;
-      --border-radius: 12px;
-      --shadow-sm: 0 1px 3px rgba(0,0,0,0.1);
-      --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06);
-      --font-mono: 'SFMono-Regular', Consolas, 'Lxgw WenKai', 'Liberation Mono', Menlo, monospace;
-    }
-
-    * {
-      margin: 0;
-      padding: 0;
-      box-sizing: border-box;
-    }
-
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
-      background: var(--bg-color);
-      color: var(--text-primary);
-      height: 100vh;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      padding: 20px;
-    }
-
-    .dashboard {
-      display: grid;
-      grid-template-columns: 300px 1fr;
-      gap: 24px;
-      width: 100%;
-      max-width: 1000px;
-      height: 600px;
-      background: var(--bg-color);
-    }
-
-    /* 左侧控制面板 */
-    .control-panel {
-      background: var(--card-bg);
-      border-radius: var(--border-radius);
-      padding: 24px;
-      box-shadow: var(--shadow-md);
-      display: flex;
-      flex-direction: column;
-      justify-content: space-between;
-    }
-
-    .header h1 {
-      font-size: 24px;
-      font-weight: 700;
-      margin-bottom: 8px;
-      background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%);
-      -webkit-background-clip: text;
-      -webkit-text-fill-color: transparent;
-    }
-
-    .header p {
-      color: var(--text-secondary);
-      font-size: 14px;
-      margin-bottom: 24px;
-    }
-
-    .task-status {
-      margin-bottom: auto;
-    }
-
-    .status-item {
-      display: flex;
-      align-items: center;
-      padding: 12px;
-      background: #f1f5f9;
-      border-radius: 8px;
-      margin-bottom: 12px;
-      font-size: 14px;
-    }
-
-    .status-dot {
-      width: 8px;
-      height: 8px;
-      border-radius: 50%;
-      margin-right: 10px;
-    }
-
-    .dot-main { background: #ef4444; box-shadow: 0 0 8px rgba(239, 68, 68, 0.4); }
-    .dot-worker { background: #3b82f6; box-shadow: 0 0 8px rgba(59, 130, 246, 0.4); }
-
-    .actions {
-      display: flex;
-      flex-direction: column;
-      gap: 12px;
-    }
-
-    /* 按钮状态控制 */
-    #btn-stop { display: none; }
-    body.running #btn-start { display: none; }
-    body.running #btn-stop { display: block; }
-
-    button {
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      width: 100%;
-      padding: 12px;
-      border: none;
-      border-radius: 8px;
-      font-size: 14px;
-      font-weight: 600;
-      cursor: pointer;
-      transition: all 0.2s ease;
-    }
-
-    .btn-start {
-      background: var(--accent-color);
-      color: white;
-    }
-    .btn-start:hover { background: var(--accent-hover); transform: translateY(-1px); }
-    .btn-start:active { transform: translateY(0); }
-
-    .btn-stop {
-      background: #fff;
-      color: var(--danger-color);
-      border: 1px solid var(--danger-color);
-    }
-    .btn-stop:hover { background: #fef2f2; }
-
-    .info-tip {
-      margin-top: 20px;
-      font-size: 12px;
-      color: var(--text-secondary);
-      text-align: center;
-      background: #f8fafc;
-      padding: 8px;
-      border-radius: 6px;
-      border: 1px dashed #cbd5e1;
-    }
-
-    /* 右侧日志面板 */
-    .log-panel {
-      background: #1e293b; /* 深色背景用于日志 */
-      border-radius: var(--border-radius);
-      box-shadow: var(--shadow-md);
-      display: flex;
-      flex-direction: column;
-      overflow: hidden;
-    }
-
-    .log-header {
-      padding: 16px 24px;
-      border-bottom: 1px solid #334155;
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      background: #0f172a;
-    }
-
-    .log-header h2 {
-      color: #e2e8f0;
-      font-size: 16px;
-      font-weight: 600;
-      display: flex;
-      align-items: center;
-      gap: 8px;
-    }
-
-    .log-box {
-      flex: 1;
-      padding: 20px;
-      overflow-y: auto;
-      font-family: var(--font-mono);
-      font-size: 13px;
-      line-height: 1.8;
-    }
-
-    /* 滚动条美化 */
-    .log-box::-webkit-scrollbar { width: 6px; }
-    .log-box::-webkit-scrollbar-track { background: #1e293b; }
-    .log-box::-webkit-scrollbar-thumb { background: #475569; border-radius: 3px; }
-
-    /* 日志条目样式 */
-    .log-item {
-      display: flex;
-      margin-bottom: 6px;
-      animation: fadeIn 0.3s ease;
-    }
-    
-    @keyframes fadeIn {
-      from { opacity: 0; transform: translateY(5px); }
-      to { opacity: 1; transform: translateY(0); }
-    }
-
-    .log-time {
-      color: #64748b;
-      margin-right: 12px;
-      min-width: 85px;
-    }
-
-    .log-content { color: #e2e8f0; }
-    .log-type-success .log-content { color: #4ade80; }
-    .log-type-info .log-content { color: #60a5fa; }
-    .log-type-error .log-content { color: #f87171; }
-
-    @media (max-width: 768px) {
-      .dashboard { grid-template-columns: 1fr; height: auto; }
-      body { height: auto; }
-      .log-panel { height: 400px; }
-    }
-  </style>
-</head>
-
-<body>
-  <div class="dashboard">
-    <!-- 左侧控制区 -->
-    <div class="control-panel">
-      <div>
-        <div class="header">
-          <h1>Hyper Scheduler</h1>
-          <p>双线程任务调度演示</p>
-        </div>
-
-        <div class="task-status">
-          <div class="status-item">
-            <span class="status-dot dot-main"></span>
-            <div>
-              <strong>主线程任务</strong>
-              <div style="font-size: 12px; color: #64748b; margin-top: 2px">每 3 秒 (driver: 'main')</div>
-            </div>
-          </div>
-          <div class="status-item">
-            <span class="status-dot dot-worker"></span>
-            <div>
-              <strong>Worker 任务</strong>
-              <div style="font-size: 12px; color: #64748b; margin-top: 2px">每 5 秒 (driver: 'worker')</div>
-            </div>
-          </div>
-        </div>
-      </div>
-
-      <div>
-        <div class="actions">
-          <button class="btn-start" id="btn-start">
-            <span style="margin-right: 8px">▶</span> 启动调度器
-          </button>
-          <button class="btn-stop" id="btn-stop">
-            <span style="margin-right: 8px">⏹</span> 停止调度器
-          </button>
-        </div>
-        <div class="info-tip">
-          💡 点击右下角悬浮球打开调试面板
-        </div>
-      </div>
-    </div>
-
-    <!-- 右侧日志区 -->
-    <div class="log-panel">
-      <div class="log-header">
-        <h2>
-          <span>📋</span> 执行日志
-        </h2>
-        <div style="font-size: 12px; color: #64748b">实时监控中...</div>
-      </div>
-      <div id="logs" class="log-box"></div>
-    </div>
-  </div>
-
-  <script src="../../dist/index.umd.cjs"></script>
-  <script>
-    const logBox = document.getElementById('logs');
-
-    function log(msg, type = 'info') {
-      const time = new Date().toLocaleTimeString('zh-CN', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
-      
-      const item = document.createElement('div');
-      item.className = `log-item log-type-${type}`;
-      
-      item.innerHTML = `
-        <span class="log-time">${time}</span>
-        <span class="log-content">${msg}</span>
-      `;
-      
-      logBox.appendChild(item);
-      
-      // 保持最新的日志可见，但如果用户向上滚动了则不强制滚动
-      const isScrolledToBottom = logBox.scrollHeight - logBox.clientHeight <= logBox.scrollTop + 10;
-      if (isScrolledToBottom || logBox.children.length <= 2) {
-          logBox.scrollTop = logBox.scrollHeight;
-      }
-    }
-
-    const { Scheduler, DevTools } = window.HyperScheduler;
-
-    const scheduler = new Scheduler({
-      debug: true,
-      plugins: [new DevTools({ 
-        theme: 'auto', 
-        language: 'zh',
-        trigger: {
-            position: 'bottom-right',
-            backgroundColor: '#3b82f6'
-        }
-      })]
-    });
-
-    // 主线程心跳 (明确指定 driver: 'main')
-    scheduler.createTask({
-      id: 'main-heartbeat',
-      schedule: '3s',
-      options: { driver: 'main' }, 
-      handler: () => {
-        log('❤️ [Main] 主线程心跳检测正常', 'error'); // 使用 error 样式红色，对应 UI 的红色点
-      }
-    });
-
-    // Worker 线程心跳 (默认即为 Worker 驱动)
-    scheduler.createTask({
-      id: 'worker-heartbeat',
-      schedule: '5s',
-      handler: () => {
-        log('💙 [Worker] 后台线程任务执行中', 'info'); // 使用 info 样式蓝色，对应 UI 的蓝色点
-      }
-    });
-
-    // 按钮事件
-    document.getElementById('btn-start').onclick = () => {
-      scheduler.start();
-      document.body.classList.add('running');
-      log('🚀 调度器系统已启动', 'success');
-    };
-
-    document.getElementById('btn-stop').onclick = () => {
-      scheduler.stop();
-      document.body.classList.remove('running');
-      log('⏹️ 调度器系统已停止', 'info');
-    };
-
-    log('✨ 系统就绪，等待启动指令...', 'info');
-  </script>
-</body>
-
-</html>

package/examples/node/simple.js

@@ -1,36 +0,0 @@
-// 注意: 在实际项目中，你应该使用 import { Scheduler } from 'hyper-scheduler';
-// 此处为了演示本地构建版本，直接引用 dist 目录下的 ESM 构建产物
-
-import { Scheduler } from '../../dist/index.js';
-
-// 创建调度器
-const scheduler = new Scheduler({ debug: true });
-
-// 辅助函数：格式化时间
-const time = () => new Date().toLocaleTimeString('zh-CN', { hour12: false });
-
-console.log('✨ 系统就绪，等待启动指令...');
-
-// 主线程心跳 (明确指定 driver: 'main')
-scheduler.createTask({
-  id: 'main-heartbeat',
-  schedule: '3s',
-  options: { driver: 'main' }, // 明确指定为主线程驱动
-  handler: () => {
-    console.log(`[${time()}] ❤️ [Main] 主线程心跳检测正常`);
-  }
-});
-
-// Worker 线程心跳 (默认即为 Worker 驱动)
-scheduler.createTask({
-  id: 'worker-heartbeat',
-  schedule: '5s',
-  handler: () => {
-    console.log(`[${time()}] 💙 [Worker] 后台线程任务执行中`);
-  }
-});
-
-// 启动调度器
-scheduler.start();
-
-console.log(`[${time()}] 🚀 调度器已启动，按 Ctrl+C 退出`);

package/examples/react-demo/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Hyper Scheduler React Demo</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.jsx"></script>
-  </body>
-</html>