@hile/schedule 2.1.1 → 3.0.2

package/AI.md

@@ -0,0 +1,263 @@
+# AI Guide For @hile/schedule
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Run cron or delayed jobs, optionally in distributed mode with Redis lock protection.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Run cron or delayed jobs | `@hile/schedule` | `packages/infrastructure.md` |
+
+
+
+# Infrastructure Helpers
+
+Packages: `@hile/typeorm`, `@hile/ioredis`, `@hile/logger`, `@hile/cache`, `@hile/schedule`, `@hile/loader`.
+
+## Use When
+
+Use these packages for database connections, Redis connections, structured logging, typed Redis caches, scheduled jobs, and file-system loaders.
+
+## Do Not Use When
+
+- Do not use default TypeORM or Redis services for multiple connections.
+- Do not use `@hile/cache` without returning `new Cache(...)` from the loader function.
+- Do not use `@hile/schedule` distributed mode without Redis lock TTLs sized for job duration.
+
+## Install
+
+```bash
+pnpm add @hile/typeorm @hile/ioredis @hile/logger @hile/cache @hile/schedule @hile/loader
+```
+
+## Imports
+
+```ts
+import typeormService, { transaction } from '@hile/typeorm'
+import redisService from '@hile/ioredis'
+import { createLogger } from '@hile/logger'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
+import { Scheduler, defineJob } from '@hile/schedule'
+import { scanDirectory, compileRoutePath, toRouterPath, normalizePath, Loader } from '@hile/loader'
+```
+
+## Copy-Paste Example
+
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
+
+const userProfile = defineCache('user:{id:string}:profile', async ({ id }) => {
+  const user = await loadUser(id)
+  return new Cache(user).setExpire(300)
+})
+
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const users = await cache.loadCache(userProfile)
+const user = await users.read({ id: 'u1' })
+```
+
+## More Examples
+
+TypeORM transaction with compensation:
+
+```ts
+await transaction(ds, async (runner, rollback) => {
+  const user = await runner.manager.save(User, input)
+  rollback(() => redis.del(`user:${user.id}`))
+  await runner.manager.save(AuditLog, { userId: user.id, action: 'create' })
+  return user
+})
+```
+
+Distributed scheduled job:
+
+```ts
+const scheduler = new Scheduler()
+scheduler.add('daily-report', '0 8 * * *', async () => {
+  await sendDailyReport()
+}, {
+  distributed: {
+    redis,
+    ttl: 60_000,
+    namespace: 'reports',
+    policy: 'skip-if-locked',
+  },
+})
+```
+
+## Compose With
+
+- Use `RedisCache` with `@hile/ioredis`.
+- Use `defineCache(..., { singleflight: true })` to reduce stampedes; internally it uses Redis locks.
+- Use scheduler distributed mode with `@hile/redis-lock`.
+- Use `Loader` only when building a new file-system based convention.
+
+## Runtime And Lifecycle Notes
+
+- `Cache(undefined)` removes the key unless negative caching is configured.
+- `Cache#setExpire(seconds)` uses seconds.
+- `defineCache` typed placeholders support `string`, `number`, and `boolean`.
+- `RedisCache.loadCache()` returns `read`, `write`, `remove`, `has`, and `multi`.
+- `RedisCache.removeTag(tag)` removes tagged cache entries.
+- `fieldable` caches use Redis hashes and cannot combine with stale or negative cache options.
+- `Scheduler.add()` supports cron strings and `{ delay }`.
+- `Scheduler.load()` reads default exports from `*.schedule.*` files produced by `defineJob()`.
+- `scanDirectory()` matches `.ts`, `.js`, `.tsx`, `.jsx`, and `.mjs`.
+
+## Anti-Patterns
+
+- Returning raw values from `defineCache` handlers instead of `new Cache(value)`.
+- Treating cache as source of truth.
+- Forgetting to destroy manually created Redis or TypeORM clients.
+- Scheduling jobs without idempotency when side effects can repeat.
+
+## Verification Checklist
+
+- Manual Redis clients call `disconnect()` during cleanup.
+- Manual TypeORM data sources call `destroy()` during cleanup.
+- Cache keys include app/tenant prefixes when shared Redis is used.
+- Scheduled jobs have clear duplicate-run policy.
+
+
+
+# Related Recipes
+
+
+
+# Queue Worker With Idempotency
+
+## Complete Example
+
+```ts
+// src/services/email-worker.boot.ts
+import { defineService, loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { RedisIdempotency, stableHash } from '@hile/redis-idempotency'
+import { RedisStreamQueue, defineQueue } from '@hile/redis-stream-queue'
+
+type EmailPayload = {
+  tenantId: string
+  userId: string
+  template: 'welcome'
+}
+
+const emailQueue = defineQueue<EmailPayload>('email')
+
+export default defineService('email.worker', async (shutdown) => {
+  const redis = await loadService(redisService)
+  const queue = new RedisStreamQueue(redis, { prefix: 'app:' })
+  const idempotency = new RedisIdempotency(redis)
+
+  const worker = queue.worker(emailQueue, async (job) => {
+    await idempotency.run(
+      `idem:email:${job.data.tenantId}:${job.jobId ?? job.id}`,
+      () => sendEmail(job.data),
+      {
+        lockTtl: 60_000,
+        resultTtl: 86_400_000,
+        fingerprint: stableHash(job.data),
+      },
+    )
+  }, {
+    group: 'email-workers',
+    consumer: process.env.HOSTNAME ?? `${process.pid}`,
+    concurrency: 8,
+    claimIdle: 60_000,
+  })
+
+  worker.start()
+  shutdown(() => worker.stop())
+
+  return { queue, worker }
+})
+```
+
+Enqueue:
+
+```ts
+await queue.add(emailQueue, {
+  tenantId: 't1',
+  userId: 'u1',
+  template: 'welcome',
+}, {
+  jobId: 'welcome:t1:u1',
+  maxAttempts: 5,
+  backoff: { type: 'exponential', baseMs: 1_000, maxMs: 60_000 },
+})
+```
+
+## File Layout
+
+```text
+src/
+  services/email-worker.boot.ts
+  queues/email.queue.ts
+```
+
+## User Intent
+
+Use this recipe for at-least-once background work where side effects must survive retries safely.
+
+## Packages To Use
+
+- `@hile/redis-stream-queue`
+- `@hile/redis-idempotency`
+- `@hile/ioredis`
+- `@hile/core`
+
+## Implementation Steps
+
+1. Define the queue and payload type.
+2. Enqueue with a stable `jobId`.
+3. Wrap side effects with `RedisIdempotency.run()`.
+4. Use business identifiers in idempotency keys.
+5. Monitor DLQ with `readDeadLetters()`.
+
+## Failure And Cleanup Behavior
+
+- Queue delivery is at-least-once.
+- Failed attempts retry until `maxAttempts`, then move to DLQ.
+- `jobId` dedupes enqueue, not side effects.
+- Idempotency caches successful results but is not exactly-once.
+
+## Verification Checklist
+
+- Handler is idempotent.
+- Idempotency key is business-derived.
+- Worker stop is registered with `shutdown`.
+- DLQ read path exists.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,83 +1,59 @@
 # @hile/schedule
 
-Declarative job scheduler based on [node-schedule](https://github.com/node-schedule/node-schedule).
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## Usage
+Run cron or delayed jobs, optionally in distributed mode with Redis lock protection.
 
-### Code-defined jobs
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-```ts
-import { Scheduler, defineJob } from '@hile/schedule'
-import { second } from '@hile/schedule'
+## When To Use
 
-const scheduler = new Scheduler()
+Use these packages for database connections, Redis connections, structured logging, typed Redis caches, scheduled jobs, and file-system loaders.
 
-// Cron expression
-scheduler.add('daily-report', '0 8 * * *', () => {
-  console.log('generating daily report...')
-})
+## Install
 
-// Delay (毫秒)
-scheduler.add('delayed-task', { delay: 5000 }, () => {
-  console.log('ran after 5 seconds')
-})
-
-scheduler.stop() // cancel all jobs
+```bash
+pnpm add @hile/schedule
 ```
 
-### Auto-load from directory
-
-Create files with `{name}.schedule.ts`:
+## Copy-Paste Example
 
 ```ts
-// tasks/daily-report.schedule.ts
-import { defineJob } from '@hile/schedule'
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
 
-export default defineJob('0 8 * * *', () => {
-  console.log('daily report generated')
+const userProfile = defineCache('user:{id:string}:profile', async ({ id }) => {
+  const user = await loadUser(id)
+  return new Cache(user).setExpire(300)
 })
-```
-
-Load them:
 
-```ts
-const scheduler = new Scheduler()
-const off = await scheduler.load(join(__dirname, 'tasks'))
-// off() to unregister all loaded jobs
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const users = await cache.loadCache(userProfile)
+const user = await users.read({ id: 'u1' })
 ```
 
-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()`
-
-取消所有任务
+## Boundaries
 
-#### `scheduler.getJobs(): JobInfo[]`
+- Do not use default TypeORM or Redis services for multiple connections.
+- Do not use `@hile/cache` without returning `new Cache(...)` from the loader function.
+- Do not use `@hile/schedule` distributed mode without Redis lock TTLs sized for job duration.
 
-返回已注册任务列表
+- Returning raw values from `defineCache` handlers instead of `new Cache(value)`.
+- Treating cache as source of truth.
+- Forgetting to destroy manually created Redis or TypeORM clients.
+- Scheduling jobs without idempotency when side effects can repeat.
 
-#### `scheduler.load(directory, options?)`
+## Verify
 
-自动发现并注册任务文件，返回注销函数
+- Manual Redis clients call `disconnect()` during cleanup.
+- Manual TypeORM data sources call `destroy()` during cleanup.
+- Cache keys include app/tenant prefixes when shared Redis is used.
+- Scheduled jobs have clear duplicate-run policy.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

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.1.1",
+  "version": "3.0.2",
   "description": "Declarative job scheduler based on node-schedule",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -23,8 +24,9 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/loader": "^2.1.1",
+    "@hile/loader": "^3.0.0",
+    "@hile/redis-lock": "^3.0.2",
     "node-schedule": "^2.1.1"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }