@hile/ioredis 2.0.2 → 3.0.0

package/AI.md

@@ -0,0 +1,350 @@
+# AI Guide For @hile/ioredis
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Create Redis clients manually or as Hile services with lifecycle cleanup.
+
+
+
+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 |
+|---|---|---|
+| Connect to Redis | `@hile/ioredis` | `packages/core-lifecycle.md`, `packages/infrastructure.md` |
+
+
+
+# Core Lifecycle, Bootstrap, CLI, Logger, Redis, TypeORM
+
+Packages: `@hile/core`, `@hile/bootstrap`, `@hile/cli`, `@hile/logger`, `@hile/ioredis`, `@hile/typeorm`.
+
+## Use When
+
+Use these packages when an app needs managed startup, singleton resources, dependency ordering, environment-file loading, graceful shutdown, logs, Redis, or SQL database connections.
+
+## Do Not Use When
+
+- Do not use `loadService()` at module top level.
+- Do not use `auto_load_packages` for file paths. It accepts package names only.
+- Do not use the default `@hile/ioredis` or `@hile/typeorm` services when one app needs multiple Redis or database connections; define separate services with separate keys.
+
+## Install
+
+```bash
+pnpm add @hile/core @hile/logger @hile/ioredis @hile/typeorm
+pnpm add -D @hile/cli
+```
+
+## Imports
+
+```ts
+import { defineService, loadService, container } from '@hile/core'
+import { createLogger } from '@hile/logger'
+import redisService, { createRedis } from '@hile/ioredis'
+import typeormService, { createDataSource, transaction } from '@hile/typeorm'
+```
+
+## Copy-Paste Example
+
+```ts
+// src/services/http.boot.ts
+import { defineService } from '@hile/core'
+import { Http } from '@hile/http'
+
+export default defineService('http', async (shutdown) => {
+  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
+  await http.load(new URL('../controllers', import.meta.url).pathname)
+  const close = await http.listen()
+  shutdown(close)
+  return http
+})
+```
+
+Run:
+
+```bash
+hile start --dev --env-file .env
+```
+
+## More Examples
+
+Use `package.json` auto-load for integration services that default-export a Hile service:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "hile start --dev --env-file .env",
+    "start": "hile start --env-file .env.prod"
+  },
+  "hile": {
+    "auto_load_packages": ["@hile/logger", "@hile/ioredis", "@hile/typeorm"]
+  }
+}
+```
+
+Inside another service, load dependencies:
+
+```ts
+import { defineService, loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import typeormService from '@hile/typeorm'
+
+export default defineService('user.service', async () => {
+  const [redis, ds] = await Promise.all([
+    loadService(redisService),
+    loadService(typeormService),
+  ])
+  return { redis, ds }
+})
+```
+
+## Compose With
+
+- Use `@hile/http` boot services to start APIs.
+- Use `@hile/model` services arrays to load TypeORM or Redis for business logic.
+- Use `@hile/cache`, `@hile/redis-lock`, queues, rate limits, and idempotency with a Redis client from `@hile/ioredis`.
+
+## Runtime And Lifecycle Notes
+
+- `defineService(key, fn)` registers a service factory and does not execute it.
+- `loadService(service)` executes the factory on first call and returns the cached value afterwards.
+- The `shutdown` callback registers teardown functions; they run in LIFO order.
+- The container tracks dependencies when service factories call `loadService()`.
+- `container.shutdown()` triggers registered teardowns.
+- `@hile/bootstrap` loads env files first, sets `NODE_ENV`, imports auto-load packages, scans boot files, and installs exit hooks.
+- `@hile/logger.createLogger()` returns `{ logger, teardown }`.
+- `@hile/ioredis.createRedis()` waits for `connect`.
+- `@hile/typeorm.createDataSource()` initializes a TypeORM `DataSource`.
+
+## Anti-Patterns
+
+- Reusing one service key for unrelated factories.
+- Missing `shutdown()` callbacks for network connections or servers.
+- Assuming TypeORM env config fills entities automatically when `TYPEORM_ENTITIES` is not set.
+- Calling `transaction()` and manually committing; the helper commits or rolls back internally.
+
+## Verification Checklist
+
+- Boot files default-export `defineService(...)`.
+- Long-lived resources register teardown callbacks.
+- `auto_load_packages` contains package names, not local files.
+- `hile start --dev` can find `src/**/*.boot.ts`.
+- Production build emits `dist/**/*.boot.js`.
+
+# 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
+
+
+
+# Redis Cache With Singleflight
+
+## Complete Example
+
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
+
+const userProfileCache = defineCache(
+  'user:{id:string}:profile',
+  async ({ id }) => {
+    const profile = await loadProfileFromDatabase(id)
+    if (!profile) return new Cache(undefined)
+    return new Cache(profile).setExpire(300)
+  },
+  {
+    singleflight: { ttl: 10_000, wait: 10_000 },
+    stale: { ttl: 60 },
+    negative: { ttl: 30 },
+    tags: (params, data) => data ? [`user:${params.id}`] : [],
+  },
+)
+
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const userProfiles = await cache.loadCache(userProfileCache)
+
+const profile = await userProfiles.read({ id: 'u1' })
+await userProfiles.remove({ id: 'u1' })
+await cache.removeTag('user:u1')
+```
+
+## File Layout
+
+```text
+src/
+  caches/user-profile.cache.ts
+  models/users/get-profile.model.ts
+```
+
+## User Intent
+
+Use this recipe when reads are expensive and Redis should provide read-through caching with stampede protection.
+
+## Packages To Use
+
+- `@hile/cache`
+- `@hile/ioredis`
+- `@hile/redis-lock` indirectly through cache singleflight
+
+## Implementation Steps
+
+1. Define a typed key with placeholders.
+2. Return `new Cache(value)` from the loader function.
+3. Add TTL with `setExpire(seconds)`.
+4. Enable `singleflight` for expensive reads.
+5. Remove cache entries after writes.
+
+## Failure And Cleanup Behavior
+
+- Stale cache serves previous values while refresh runs.
+- Negative cache stores missing values only when configured.
+- Cache is not source of truth; database writes should remove or refresh related keys.
+
+## Verification Checklist
+
+- Cache handler returns `Cache`.
+- Key params match placeholders.
+- Redis prefix is app-specific.
+- Update flows call `remove()` or `removeTag()`.
+
+
+
+# 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,67 +1,64 @@
 # @hile/ioredis
 
-基于 `@hile/core` 的 Redis 集成：将 ioredis 客户端封装为 Hile 服务（单例、可优雅断连）。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Create Redis clients manually or as Hile services with lifecycle cleanup.
 
-```bash
-pnpm add @hile/ioredis
-```
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-同时安装依赖：`@hile/core`、`ioredis`。
+## When To Use
 
-## 快速开始
+Use these packages when an app needs managed startup, singleton resources, dependency ordering, environment-file loading, graceful shutdown, logs, Redis, or SQL database connections.
 
-```typescript
-import { loadService } from '@hile/core'
-import ioredisService from '@hile/ioredis'
+## Install
 
-const redis = await loadService(ioredisService)
-// 使用 redis.get/set 等 ioredis API
+```bash
+pnpm add @hile/ioredis
 ```
 
-默认导出使用稳定的服务 key（实现中为 `Symbol.for` + 包名）。需要多个 Redis 连接时请为每个连接使用不同的 `defineService(key, ...)`。
-
-## 环境变量
-
-默认客户端从以下环境变量读取配置：
+## Copy-Paste Example
 
-| 变量 | 说明 |
-|------|------|
-| `REDIS_HOST` | Redis 主机 |
-| `REDIS_PORT` | Redis 端口（字符串会转为数字） |
-| `REDIS_USERNAME` | Redis 用户名 |
-| `REDIS_PASSWORD` | Redis 密码 |
-| `REDIS_DB` | Redis 数据库编号，默认 `0` |
+```ts
+// src/services/http.boot.ts
+import { defineService } from '@hile/core'
+import { Http } from '@hile/http'
 
-行为说明：
+export default defineService('http', async (shutdown) => {
+  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
+  await http.load(new URL('../controllers', import.meta.url).pathname)
+  const close = await http.listen()
+  shutdown(close)
+  return http
+})
+```
 
-- 服务首次加载时创建连接并等待 `connect` 事件
-- 进程退出时通过 Hile 的 shutdown 调用 `client.disconnect()`
+Run:
 
-## 与 @hile/cli 一起使用
+```bash
+hile start --dev --env-file .env
+```
 
-可在 `package.json` 配置自动加载：
+## Boundaries
 
-```json
-{
-  "hile": {
-    "auto_load_packages": ["@hile/ioredis"]
-  }
-}
-```
+- Do not use `loadService()` at module top level.
+- Do not use `auto_load_packages` for file paths. It accepts package names only.
+- Do not use the default `@hile/ioredis` or `@hile/typeorm` services when one app needs multiple Redis or database connections; define separate services with separate keys.
 
-这样应用启动时会自动建立 Redis 连接，退出时自动断开。
+- Reusing one service key for unrelated factories.
+- Missing `shutdown()` callbacks for network connections or servers.
+- Assuming TypeORM env config fills entities automatically when `TYPEORM_ENTITIES` is not set.
+- Calling `transaction()` and manually committing; the helper commits or rolls back internally.
 
-## 开发
+## Verify
 
-```bash
-pnpm install
-pnpm build
-pnpm dev
-pnpm test
-```
+- Boot files default-export `defineService(...)`.
+- Long-lived resources register teardown callbacks.
+- `auto_load_packages` contains package names, not local files.
+- `hile start --dev` can find `src/**/*.boot.ts`.
+- Production build emits `dist/**/*.boot.js`.
 
-## 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/ioredis",
-  "version": "2.0.2",
+  "version": "3.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -21,8 +22,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/core": "^2.0.1",
+    "@hile/core": "^3.0.0",
     "ioredis": "^5.11.0"
   },
-  "gitHead": "d2495d1c31f5c5fbc25c9d447c8f32b484ab0340"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }