@hile/schedule 3.0.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,123 +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. -->
 
-从 3.0.0 开始，新增或重构的 Hile 架构包统一进入 3.x 版本线，2.x 时代结束。
+Run cron or delayed jobs, optionally in distributed mode with Redis lock protection.
 
-## Usage
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-### Code-defined jobs
+## When To Use
 
-```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...')
-})
+Use these packages for database connections, Redis connections, structured logging, typed Redis caches, scheduled jobs, and file-system loaders.
 
-// Delay (毫秒)
-scheduler.add('delayed-task', { delay: 5000 }, () => {
-  console.log('ran after 5 seconds')
-})
+## Install
 
-scheduler.stop() // cancel all jobs
+```bash
+pnpm add @hile/schedule
 ```
 
-### 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.
+## Copy-Paste Example
 
 ```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)
-  },
-})
-```
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
 
-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`:
-
-```ts
-// tasks/daily-report.schedule.ts
-import { defineJob } from '@hile/schedule'
-
-export default defineJob('daily-report', '0 8 * * *', () => {
-  console.log('daily report generated')
-}, {
-  distributed: { redis, ttl: 60_000 },
+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(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, 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, 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)`
-
-#### `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/schedule",
-  "version": "3.0.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,9 +24,9 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/loader": "^2.1.1",
-    "@hile/redis-lock": "^3.0.1",
+    "@hile/loader": "^3.0.0",
+    "@hile/redis-lock": "^3.0.2",
     "node-schedule": "^2.1.1"
   },
-  "gitHead": "88f52fb95743f86761778776aff23631fcf9d821"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }