@hile/schedule 2.0.1 → 3.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 Declarative job scheduler based on [node-schedule](https://github.com/node-schedule/node-schedule).
 
+从 3.0.0 开始，新增或重构的 Hile 架构包统一进入 3.x 版本线，2.x 时代结束。
+
 ## Usage
 
 ### Code-defined jobs
@@ -25,6 +27,29 @@ scheduler.add('delayed-task', { delay: 5000 }, () => {
 scheduler.stop() // cancel all jobs
 ```
 
+### Distributed jobs
+
+`@hile/schedule` can use `@hile/redis-lock` to make a job run on only one process when several app instances register the same schedule.
+
+```ts
+const scheduler = new Scheduler()
+
+scheduler.add('daily-report', '0 8 * * *', async () => {
+  await generateDailyReport()
+}, {
+  distributed: {
+    redis,
+    ttl: 60_000,
+  },
+  onSkip(info) {
+    console.log('job skipped because another instance owns the lock', info.id)
+  },
+})
+```
+
+The default policy is `skip-if-locked`: if another process owns `schedule:{namespace}:{jobId}`, this run is skipped. Without `namespace`, the default namespace is `default`. Use `policy: 'wait'` with `wait` when a delayed wait is acceptable.
+Set `distributed.namespace` when several apps share the same Redis but can run jobs with the same id independently.
+
 ### Auto-load from directory
 
 Create files with `{name}.schedule.ts`:
@@ -33,8 +58,10 @@ Create files with `{name}.schedule.ts`:
 // tasks/daily-report.schedule.ts
 import { defineJob } from '@hile/schedule'
 
-export default defineJob('0 8 * * *', () => {
+export default defineJob('daily-report', '0 8 * * *', () => {
   console.log('daily report generated')
+}, {
+  distributed: { redis, ttl: 60_000 },
 })
 ```
 
@@ -55,14 +82,27 @@ await scheduler.load('./jobs', { suffix: 'job' })
 
 ### API
 
-#### `defineJob(expression, handler)`
+#### `defineJob(id, expression, handler, options?)`
+
+- `id: string | number` — stable task id. Recommended for distributed jobs and logs.
+- `expression: string | { delay: number }` — cron 表达式或延迟毫秒数
+- Returns `{ id, type: 'job', expression, handler, options }`
+
+#### `defineJob(expression, handler, options?)`
 
 - `expression: string | { delay: number }` — cron 表达式或延迟毫秒数
-- Returns `{ id: number, type: 'job', expression, handler }`
+- Returns `{ id: number, idAutoGenerated: true, type: 'job', expression, handler, options }`
+- When loaded through `scheduler.load()`, auto-generated ids are replaced with the file route path, so `daily-report.schedule.ts` registers as `/daily-report`.
 
-#### `scheduler.add(id, expression | { delay }, handler)`
+#### `scheduler.add(id, expression | { delay }, handler, options?)`
 
 - `id: string | number` — 任务唯一标识，重复添加抛异常
+- `options.distributed.redis` — Redis 客户端
+- `options.distributed.ttl` — job 锁租约，单位毫秒
+- `options.distributed.namespace` — 可选，默认锁 key 的命名空间
+- `options.distributed.lockKey` — 可选，自定义锁 key，默认 `schedule:{namespace || 'default'}:{id}`
+- `options.onSkip(info)` — 没拿到锁时回调
+- `options.onError(error, info)` — handler 或锁流程异常时回调
 
 #### `scheduler.remove(id)`
 

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import { Scheduler } from './scheduler.js';
-import type { JobDefinition, JobHandler } from './types.js';
+import type { JobDefinition, JobExpression, JobHandler, JobId, JobOptions } 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;
+export { ScheduleJobRunner } from './runner.js';
+export type { DistributedJobOptions, JobDefinition, JobExpression, JobHandler, JobId, JobInfo, JobOptions, JobRunInfo, } from './types.js';
+export declare function defineJob<TId extends JobId>(id: TId, expression: JobExpression, handler: JobHandler, options?: JobOptions): JobDefinition<TId>;
+export declare function defineJob(expression: JobExpression, handler: JobHandler, options?: JobOptions): JobDefinition<number>;

package/dist/index.js

@@ -1,6 +1,26 @@
 import { Scheduler } from './scheduler.js';
 export { Scheduler };
+export { ScheduleJobRunner } from './runner.js';
 let _jobId = 1;
-export function defineJob(expression, handler) {
-    return { id: _jobId++, type: 'job', expression, handler };
+export function defineJob(idOrExpression, expressionOrHandler, handlerOrOptions, maybeOptions) {
+    if (typeof expressionOrHandler === 'function') {
+        return {
+            id: _jobId++,
+            idAutoGenerated: true,
+            type: 'job',
+            expression: idOrExpression,
+            handler: expressionOrHandler,
+            options: handlerOrOptions,
+        };
+    }
+    if (typeof handlerOrOptions !== 'function') {
+        throw new TypeError('defineJob handler is required');
+    }
+    return {
+        id: idOrExpression,
+        type: 'job',
+        expression: expressionOrHandler,
+        handler: handlerOrOptions,
+        options: maybeOptions,
+    };
 }

package/dist/runner.d.ts

@@ -0,0 +1,11 @@
+import type { JobHandler, JobOptions, JobRunInfo } from './types.js';
+export declare class ScheduleJobRunner {
+    private readonly options;
+    private readonly locks?;
+    constructor(options?: JobOptions);
+    createHandler(handler: JobHandler, info: JobRunInfo): () => void;
+    private run;
+    private runDistributed;
+    private resolveLockKey;
+    private reportError;
+}

package/dist/runner.js

@@ -0,0 +1,70 @@
+import { LockConflictError, LockTimeoutError, RedisLock, } from '@hile/redis-lock';
+function isLockUnavailableError(error) {
+    return error instanceof LockConflictError || error instanceof LockTimeoutError;
+}
+export class ScheduleJobRunner {
+    options;
+    locks;
+    constructor(options = {}) {
+        this.options = options;
+        if (options.distributed) {
+            this.locks = new RedisLock(options.distributed.redis);
+        }
+    }
+    createHandler(handler, info) {
+        return () => {
+            void this.run(handler, info).catch(error => {
+                this.reportError(error, info);
+            });
+        };
+    }
+    async run(handler, info) {
+        const distributed = this.options.distributed;
+        if (!distributed) {
+            await handler(info);
+            return;
+        }
+        try {
+            await this.runDistributed(handler, info, distributed);
+        }
+        catch (error) {
+            if (isLockUnavailableError(error)) {
+                await this.options.onSkip?.(info);
+                return;
+            }
+            throw error;
+        }
+    }
+    async runDistributed(handler, info, distributed) {
+        if (!this.locks)
+            throw new Error('Distributed schedule runner was not initialized');
+        const lockKey = this.resolveLockKey(info, distributed);
+        const wait = distributed.policy === 'wait' ? distributed.wait ?? distributed.ttl : 0;
+        await this.locks.withLock(lockKey, {
+            ttl: distributed.ttl,
+            wait,
+            pollInterval: distributed.pollInterval,
+            maxPollInterval: distributed.maxPollInterval,
+            renew: distributed.renew,
+        }, async () => {
+            await handler(info);
+        });
+    }
+    resolveLockKey(info, distributed) {
+        if (typeof distributed.lockKey === 'function')
+            return distributed.lockKey(info);
+        if (distributed.lockKey !== undefined)
+            return distributed.lockKey;
+        return `schedule:${distributed.namespace ?? 'default'}:${info.id}`;
+    }
+    reportError(error, info) {
+        try {
+            const reported = this.options.onError?.(error, info);
+            if (reported)
+                void reported.catch(() => { });
+        }
+        catch {
+            // Error reporters should not turn handled job failures into unhandled rejections.
+        }
+    }
+}

package/dist/scheduler.d.ts

@@ -1,16 +1,11 @@
-import type { JobHandler } from './types.js';
-export type JobInfo = {
-    id: string;
-    type: 'cron' | 'delay';
-    expression: string;
-};
+import type { JobHandler, JobInfo, JobOptions } from './types.js';
 export declare class Scheduler {
     private jobs;
     private meta;
-    add(id: string | number, expression: string, handler: JobHandler): void;
+    add(id: string | number, expression: string, handler: JobHandler, options?: JobOptions): void;
     add(id: string | number, options: {
         delay: number;
-    }, handler: JobHandler): void;
+    }, handler: JobHandler, jobOptions?: JobOptions): void;
     remove(id: string | number): void;
     stop(): void;
     getJobs(): JobInfo[];
@@ -24,4 +19,5 @@ export declare class Scheduler {
     load(directory: string, options?: {
         suffix?: string;
     }): Promise<() => void>;
+    private resolveLoadedJobId;
 }

package/dist/scheduler.js

@@ -1,33 +1,32 @@
 import { scheduleJob } from 'node-schedule';
 import { pathToFileURL } from 'node:url';
+import { ScheduleJobRunner } from './runner.js';
 import { scanDirectory } from '@hile/loader';
 export class Scheduler {
     jobs = new Map();
     meta = new Map();
-    add(id, exprOrOpts, handler) {
+    add(id, exprOrOpts, handler, options) {
         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 });
+            const info = { id: key, type: 'cron', expression: exprOrOpts };
+            const safeHandler = new ScheduleJobRunner(options).createHandler(handler, info);
+            const job = scheduleJob(exprOrOpts, safeHandler);
+            if (!job)
+                throw new Error(`Failed to schedule job "${key}" with expression "${exprOrOpts}"`);
+            this.jobs.set(key, job);
+            this.meta.set(key, { type: info.type, expression: info.expression });
         }
         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}` });
+            const info = { id: key, type: 'delay', expression: `delay:${exprOrOpts.delay}` };
+            const safeHandler = new ScheduleJobRunner(options).createHandler(handler, info);
+            const job = scheduleJob(date, safeHandler);
+            if (!job)
+                throw new Error(`Failed to schedule job "${key}" with delay ${exprOrOpts.delay}`);
+            this.jobs.set(key, job);
+            this.meta.set(key, { type: info.type, expression: info.expression });
         }
     }
     remove(id) {
@@ -63,23 +62,33 @@ export class Scheduler {
     async load(directory, options) {
         const files = await scanDirectory(directory, { suffix: options?.suffix || 'schedule' });
         const offFns = [];
-        for (const file of files) {
-            const mod = await import(pathToFileURL(file.absolute).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);
+        try {
+            for (const file of files) {
+                const mod = await import(pathToFileURL(file.absolute).href);
+                const jobDef = mod.default;
+                if (!jobDef || jobDef.type !== 'job')
+                    continue;
+                const key = this.resolveLoadedJobId(jobDef, file);
+                if (typeof jobDef.expression === 'string') {
+                    this.add(key, jobDef.expression, jobDef.handler, jobDef.options);
+                }
+                else {
+                    this.add(key, jobDef.expression, jobDef.handler, jobDef.options);
+                }
+                offFns.push(() => this.remove(key));
             }
-            offFns.push(() => this.remove(key));
+        }
+        catch (error) {
+            for (const off of offFns.reverse())
+                off();
+            throw error;
         }
         return () => {
             for (const off of offFns)
                 off();
         };
     }
+    resolveLoadedJobId(jobDef, file) {
+        return jobDef.idAutoGenerated ? file.routePath : String(jobDef.id);
+    }
 }

package/dist/types.d.ts

@@ -1,9 +1,36 @@
-export type JobHandler = () => Promise<void> | void;
-export type JobDefinition = {
-    id: number;
+import type { RedisLockLike, WithLockOptions } from '@hile/redis-lock';
+export type JobRunInfo = {
+    id: string;
+    type: 'cron' | 'delay';
+    expression: string;
+};
+export type JobInfo = JobRunInfo;
+export type JobHandler = (info: JobRunInfo) => Promise<void> | void;
+export type JobId = string | number;
+export type JobExpression = string | {
+    delay: number;
+};
+export type DistributedJobOptions = {
+    redis: RedisLockLike;
+    ttl: number;
+    namespace?: string;
+    lockKey?: string | ((info: JobRunInfo) => string);
+    policy?: 'skip-if-locked' | 'wait';
+    wait?: number;
+    pollInterval?: number;
+    maxPollInterval?: number;
+    renew?: WithLockOptions['renew'];
+};
+export type JobOptions = {
+    distributed?: DistributedJobOptions;
+    onError?: (error: unknown, info: JobRunInfo) => Promise<void> | void;
+    onSkip?: (info: JobRunInfo) => Promise<void> | void;
+};
+export type JobDefinition<TId extends JobId = JobId> = {
+    id: TId;
+    idAutoGenerated?: boolean;
     type: 'job';
-    expression: string | {
-        delay: number;
-    };
+    expression: JobExpression;
     handler: JobHandler;
+    options?: JobOptions;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/schedule",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "description": "Declarative job scheduler based on node-schedule",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,8 +23,9 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/loader": "^2.0.1",
+    "@hile/loader": "^2.1.1",
+    "@hile/redis-lock": "^3.0.1",
     "node-schedule": "^2.1.1"
   },
-  "gitHead": "2c8011db01f2815e5ce34de964d5492640396828"
+  "gitHead": "88f52fb95743f86761778776aff23631fcf9d821"
 }