@hile/schedule 2.0.0

package/README.md

@@ -0,0 +1,83 @@
+# @hile/schedule
+
+Declarative job scheduler based on [node-schedule](https://github.com/node-schedule/node-schedule).
+
+## Usage
+
+### Code-defined jobs
+
+```ts
+import { Scheduler, defineJob } from '@hile/schedule'
+import { second } from '@hile/schedule'
+
+const scheduler = new Scheduler()
+
+// Cron expression
+scheduler.add('daily-report', '0 8 * * *', () => {
+  console.log('generating daily report...')
+})
+
+// Delay (毫秒)
+scheduler.add('delayed-task', { delay: 5000 }, () => {
+  console.log('ran after 5 seconds')
+})
+
+scheduler.stop() // cancel all jobs
+```
+
+### Auto-load from directory
+
+Create files with `{name}.schedule.ts`:
+
+```ts
+// tasks/daily-report.schedule.ts
+import { defineJob } from '@hile/schedule'
+
+export default defineJob('0 8 * * *', () => {
+  console.log('daily report generated')
+})
+```
+
+Load them:
+
+```ts
+const scheduler = new Scheduler()
+const off = await scheduler.load(join(__dirname, 'tasks'))
+// off() to unregister all loaded jobs
+```
+
+Custom suffix via `suffix` option:
+
+```ts
+await scheduler.load('./jobs', { suffix: 'job' })
+// loads *.job.ts, *.job.js, etc.
+```
+
+### API
+
+#### `defineJob(expression, handler)`
+
+- `expression: string | { delay: number }` — cron 表达式或延迟毫秒数
+- Returns `{ id: number, type: 'job', expression, handler }`
+
+#### `scheduler.add(id, expression | { delay }, handler)`
+
+- `id: string | number` — 任务唯一标识，重复添加抛异常
+
+#### `scheduler.remove(id)`
+
+#### `scheduler.stop()`
+
+取消所有任务
+
+#### `scheduler.getJobs(): JobInfo[]`
+
+返回已注册任务列表
+
+#### `scheduler.load(directory, options?)`
+
+自动发现并注册任务文件，返回注销函数
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { Scheduler } from './scheduler.js';
+import type { JobDefinition, JobHandler } from './types.js';
+export { Scheduler };
+export type { JobInfo } from './scheduler.js';
+export type { JobDefinition, JobHandler };
+export declare function defineJob(expression: string | {
+    delay: number;
+}, handler: () => Promise<void> | void): JobDefinition;

package/dist/index.js

@@ -0,0 +1,6 @@
+import { Scheduler } from './scheduler.js';
+export { Scheduler };
+let _jobId = 1;
+export function defineJob(expression, handler) {
+    return { id: _jobId++, type: 'job', expression, handler };
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,27 @@
+import type { JobHandler } from './types.js';
+export type JobInfo = {
+    id: string;
+    type: 'cron' | 'delay';
+    expression: string;
+};
+export declare class Scheduler {
+    private jobs;
+    private meta;
+    add(id: string | number, expression: string, handler: JobHandler): void;
+    add(id: string | number, options: {
+        delay: number;
+    }, handler: JobHandler): void;
+    remove(id: string | number): void;
+    stop(): void;
+    getJobs(): JobInfo[];
+    /**
+     * 从目录自动加载 schedule 任务文件
+     * 文件后缀: {suffix}.ts/.js，default export 须为 defineJob 返回值
+     * @param directory 目录路径
+     * @param options.suffix 文件后缀标记，默认 'schedule'
+     * @returns 注销函数
+     */
+    load(directory: string, options?: {
+        suffix?: string;
+    }): Promise<() => void>;
+}

package/dist/scheduler.js

@@ -0,0 +1,88 @@
+import { scheduleJob } from 'node-schedule';
+import { glob } from 'glob';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+export class Scheduler {
+    jobs = new Map();
+    meta = new Map();
+    add(id, exprOrOpts, handler) {
+        const key = String(id);
+        if (this.jobs.has(key))
+            throw new Error(`Job "${key}" already exists`);
+        // 包装 handler，捕获异步错误防止 node-schedule 未捕获 rejection
+        const safeHandler = () => {
+            try {
+                const result = handler();
+                if (result && typeof result.catch === 'function') {
+                    result.catch(() => { });
+                }
+            }
+            catch {
+                // handler 同步错误也不应影响调度器
+            }
+        };
+        if (typeof exprOrOpts === 'string') {
+            this.jobs.set(key, scheduleJob(exprOrOpts, safeHandler));
+            this.meta.set(key, { type: 'cron', expression: exprOrOpts });
+        }
+        else {
+            const date = new Date(Date.now() + exprOrOpts.delay);
+            this.jobs.set(key, scheduleJob(date, safeHandler));
+            this.meta.set(key, { type: 'delay', expression: `delay:${exprOrOpts.delay}` });
+        }
+    }
+    remove(id) {
+        const key = String(id);
+        const job = this.jobs.get(key);
+        if (job) {
+            job.cancel();
+            this.jobs.delete(key);
+            this.meta.delete(key);
+        }
+    }
+    stop() {
+        for (const job of this.jobs.values()) {
+            job.cancel();
+        }
+        this.jobs.clear();
+        this.meta.clear();
+    }
+    getJobs() {
+        return Array.from(this.meta.entries()).map(([id, m]) => ({
+            id,
+            type: m.type,
+            expression: m.expression,
+        }));
+    }
+    /**
+     * 从目录自动加载 schedule 任务文件
+     * 文件后缀: {suffix}.ts/.js，default export 须为 defineJob 返回值
+     * @param directory 目录路径
+     * @param options.suffix 文件后缀标记，默认 'schedule'
+     * @returns 注销函数
+     */
+    async load(directory, options) {
+        const suffix = options?.suffix || 'schedule';
+        const files = await glob(`**/*.${suffix}.{ts,js,tsx,jsx,mjs}`, { cwd: directory });
+        const offFns = [];
+        for (const file of files) {
+            const filePath = resolve(directory, file);
+            const mod = await import(pathToFileURL(filePath).href);
+            const jobDef = mod.default;
+            if (!jobDef || jobDef.type !== 'job')
+                continue;
+            const key = String(jobDef.id);
+            if (typeof jobDef.expression === 'string') {
+                this.add(key, jobDef.expression, jobDef.handler);
+            }
+            else {
+                this.add(key, jobDef.expression, jobDef.handler);
+            }
+            offFns.push(() => this.remove(key));
+        }
+        return () => {
+            for (const off of offFns)
+                off();
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export type JobHandler = () => Promise<void> | void;
+export type JobDefinition = {
+    id: number;
+    type: 'job';
+    expression: string | {
+        delay: number;
+    };
+    handler: JobHandler;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hile/schedule",
+  "version": "2.0.0",
+  "description": "Declarative job scheduler based on node-schedule",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node-schedule": "^2.1.7",
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "glob": "^13.0.6",
+    "node-schedule": "^2.1.1"
+  },
+  "gitHead": "8e0fd1f78b5a8abd21218d1f596ada2533a0c8e7"
+}