# Aragami

[English](README.md) · [简体中文](README-CN.md)

**Aragami 是面向 TypeScript 的 Redis ORM / Utility**，同时提供对应的内存实现。

它把应用里两类常见需求放进同一套接口：保存有类型的模型，以及围绕这些模型协调工作。类描述数据，元数据描述资源身份，Aragami 负责序列化、类实例恢复，以及缓存、锁、队列、广播和选举背后的 Redis 操作。

同一个用户模型可以按 ID 缓存，在更新时加锁，也可以作为消息发布出去。每项能力使用独立的存储命名空间，而应用始终沿用 **「类 namespace＋自己的 key」** 来组织资源。

| 应用中的需求 | Aragami 提供的能力 |
| --- | --- |
| 复用已经加载的资料或计算结果 | 类型化缓存、TTL 和缺失时自动加载 |
| 协调多个操作对共享资源的访问 | 普通独占锁和读写锁 |
| 把工作交给后台消费者 | 带确认与恢复的队列、持续消费 worker |
| 到指定时间后再执行工作 | 同一个队列中的延时任务 |
| 把事件通知给每个感兴趣的订阅者 | 实时 Pub/Sub，以及回调和 RxJS 接口 |
| 从在线成员中选出一个或多个协调者 | 选举状态和 leader 判定 |

## 名字来源与设计理念

**Aragami** 的名字来自曲师 **xi** 的歌曲 **《Aragami》**。

🎵 [Aragami / xi — xi Official 的 YouTube 视频](https://www.youtube.com/watch?v=0372jx-bTzA)

库的设计让资源身份靠近模型定义，也让应用从本地内存切换到共享 Redis 状态时，继续使用同一套操作方式。

## 开始使用

先在应用中安装：

```sh
npm install aragami
```

需要让多个应用进程共享状态时，创建实例并配置 Redis 连接：

```ts
import { Aragami } from 'aragami';

const aragami = new Aragami({
  redis: { uri: 'redis://127.0.0.1:6379' },
});
```

改为 `new Aragami()` 就会使用内存实现，适合本地开发，以及不需要 Redis 服务的测试。两种实现使用相同的公共 API，但状态共享范围有所不同，见[驱动说明](#内存redis-与自定义-driver)。

包提供 CommonJS、原生 ESM 和 TypeScript 声明，入口会加载 `reflect-metadata`。使用后面的装饰器示例时，请在 TypeScript 的 `compilerOptions` 中启用 `experimentalDecorators` 和 `emitDecoratorMetadata`。

Redis 模式最低支持 **Redis 5.0.0**，需要启用 Lua 脚本和 Pub/Sub。完整 Redis 测试及已构建的 CJS／原生 ESM 包均在 **5.0.0** 和 **7.4.9** 上验证过。队列、读写锁和选举脚本结合 Redis `TIME` 与写操作，依赖 [Redis 5.0 起默认启用的脚本效果复制](https://redis.io/docs/latest/develop/programmability/eval-intro/#replicating-commands-instead-of-scripts)。

Rx 接口使用 **RxJS `^7.8.2`**，符合 [NestJS 12](https://github.com/nestjs/nest/blob/v12.1.2/packages/core/package.json) 声明的 `^7.1.0` 依赖范围。

## 一个模型，两层 key

Aragami 围绕类组织资源。第一层是类的 namespace，由 `@CachePrefix` 指定，没有时使用类名；第二层是 namespace 内某个值、队列、消息主题或资源自己的 key。

例如，用户模型属于 `users`，用户 ID 用来区分其中的资源：

```ts
import { CachePrefix, CacheKey, LockKey } from 'aragami';

@CachePrefix('users')
class User {
  @CacheKey()
  @LockKey((id) => id)
  id!: string;
  name!: string;
}
```

这里的 `CacheKey` 决定缓存条目的身份，`LockKey` 决定锁和选举使用的资源身份。这个例子让两者都直接使用 ID；不传工厂函数的 `@LockKey()` 默认生成 `字段名_字段值`，例如 `id_u1`。key 装饰器也支持方法、getter 和异步工厂。

显式 key 会覆盖 `CacheKey`。队列入队和消息发布在没有显式 key 时使用 `CacheKey`，没有元数据时使用 `default`；队列消费、查询和消息订阅使用传入的 key，省略时使用字面值 `default`。锁也支持字符串资源 key。选举可以传字符串、对象，或省略参数；没有 `LockKey` 的对象使用类 namespace＋`default`。

缓存、普通锁、读写锁、队列、Pub/Sub 和选举各自独立。即使逻辑 key 相同，也不会混合状态，因此同一个模型可以在多项能力中复用。下面的示例沿用这里的 `aragami` 和 `User`。

## 类型化缓存与类恢复

缓存用于保存加载或计算成本较高的值。Aragami 在这个操作上加入模型映射：读出缓存的 `User` 时恢复为 `User` 实例，应用可以继续使用类的方法和结构。

`set` 支持传入实例，或「类＋对象」；`get` 按类和 key 读取：

```ts
const user = await aragami.set(User, { id: 'u1', name: 'Alice' });
const cached = await aragami.get(User, 'u1');
await aragami.set(user, { ttl: 30_000 });
```

返回值是模型实例，缓存缺失时返回 `undefined`。`@CastType(() => Child)` 描述嵌套模型，也适用于数组元素；`@CastType(() => Date)` 可以恢复日期字段。这种类、key 与序列化数据之间的映射，就是 Aragami 的 ORM 部分。

TTL 决定缓存保留多久，单位为毫秒。优先级是显式 `ttl`、模型上的 `@CacheTTL`、`defaultTTL`，最后默认为 `0`，表示不失效。显式 key，包括空字符串，都会覆盖模型元数据。

需要检查或清理时，`has` 判断是否存在，`del` 删除条目，`keys`、`values`、`entries` 枚举类 namespace 中的数据，`clear` 清理该 namespace。枚举和清理方法可以传入字面值 key 前缀，便于操作一组相关缓存。

### 缓存缺失时加载

`cache` 把「先读取，缺失时加载并写入」合成一次调用。已有缓存时直接返回模型，没有时执行你的 loader，适合从数据库或其他服务加载用户资料：

```ts
const profile = await aragami.cache(User, 'u1', () => fetchUser('u1'));
```

来源 key 为空或缺失时直接执行 loader，不进行缓存；loader 返回 null／undefined 时也不会写入。希望得到可重复调用的函数时，可以用 `useCache` 包装 loader，复用同样的行为。

## 普通独占锁

独占锁让同一资源在同一时间只被一个操作处理。两个请求可能同时更新同一个用户，或多个进程需要协调一项共享操作时，可以用锁划定互斥范围。Aragami 从对象的 `LockKey` 提取资源身份，让定义留在模型旁边。

获取锁后执行回调，回调结束时释放：

```ts
await aragami.lock(user, () => saveUser(user));
const free = await aragami.isFree(user);
```

资源也可以是字符串，或由对象和字符串组成的数组。多资源锁会去重重复 key，空数组则直接执行。同步和异步回调都会保留返回值和异常；`useLock` 可以把相同行为包装成可复用函数。

Redis 锁使用租约，执行回调期间自动续租，并通过释放通知和轮询唤醒等待者。获取超时会抛出 `LockAcquireTimeoutError`。进程长时间暂停或 Redis 不可用仍可能使租约失效；回调不会被强制取消，外部写入也没有 fencing 保护。

`lock.multiKeyBypass` 默认 `false`。开启后，本地锁一次性获取全部 key，等待 B 的请求不会提前占住 A；`redis.lock.multiKeyBypass` 可覆盖公共设置。Redis 开启 `stacked` 且启用绕过时，本地只协调单次获取尝试；Redis 本身始终原子获取全部 key。普通锁和读写锁的状态相互独立。

## 读写锁

读写锁允许多个读者共享资源，同时让写者独占。适合读取可以并发，但修改必须等待读者结束，并在修改期间阻止重叠读写的场景。

第一个参数是导出的 TypeScript enum `RWLockMode`，包含 `READ` 和 `WRITE`：

```ts
import { RWLockMode } from 'aragami';

await aragami.rwLock(RWLockMode.READ, user, () => readUser(user));
await aragami.rwLock(RWLockMode.WRITE, user, () => saveUser(user));
```

读写锁沿用普通锁的对象元数据和多资源规则，但使用独立的物理命名空间及配置。`isRWFree(mode, resource)` 查询指定模式能否进入，`useRWLock` 则把它包装成函数。

默认策略为 `RWLockPriority.WRITE_FIRST`。`READ_FIRST` 优先处理等待读者，`FIFO` 按首次登记顺序处理互斥请求。读读可以并发，无关 key 可以继续执行，已有持锁者不会被抢占。只有未提供 `writerPriorityStrategy` 时，才读取已弃用的 `writerPriority`。

```ts
import { Aragami, RWLockPriority, FifoRWLockPriorityStrategy } from 'aragami';

const ordered = new Aragami({
  rwLock: { writerPriorityStrategy: RWLockPriority.FIFO },
});
const samePolicy = new Aragami({
  rwLock: { writerPriorityStrategy: new FifoRWLockPriorityStrategy() },
});
```

三个导出的驱动分别是 `ReadFirstRWLockPriorityStrategy`、`WriteFirstRWLockPriorityStrategy`、`FifoRWLockPriorityStrategy`，给读／写请求的分数分别为 `1/0`、`0/1`、`0/0`。分数越高越优先，同分的互斥请求按 FIFO 排队。

`rwLock.multiKeyBypass` 默认 `false`：等待 `[A, B]` 的请求，在 B 被持有时也可以挡住 A。开启后，如果先来的请求因 B 上的互斥持锁者而无法进入，就允许 A 上的请求绕过。判断仅考虑候选请求资源之外的实际持锁者。`isRWFree` 使用相同规则，查询请求的等待时长为零。

自定义驱动接收同步纯函数，在 instance 构造时编译为适用于 Redis 的 Lua：

```ts
import { RWLockPriorityStrategy } from 'aragami';

class AgingWriterStrategy
  extends RWLockPriorityStrategy<{ promoteAfterMs: number }> {
  constructor(promoteAfterMs = 30_000) {
    super((request, context) => {
      if (request.mode === 'WRITE' &&
          request.waitedMs >= context.params.promoteAfterMs) return 2;
      return request.mode === 'READ' ? 1 : 0;
    }, { promoteAfterMs });
  }
}

const app = new Aragami({
  rwLock: {
    writerPriorityStrategy: new AgingWriterStrategy(),
    multiKeyBypass: true,
  },
});
```

函数收到只读请求（`id`、`mode`、去重后的逻辑 `keys`、`enqueuedAt`、`waitedMs`、`sequence`）和上下文（`now`、包含当前请求的完整有序 `waiting` 快照、固定 `params`）。时间单位为毫秒。返回值必须是有限数值，负数和小数也有效；零表示优先级，不表示拒绝或等待时间。`getPriority(request, state)` 在本地执行同一函数。`params`、`luaSource`、`fingerprint` 为只读属性，复用 instance 不会重新编译。

函数不能捕获外部变量、使用 `this`、导入引用、异步、I/O、时钟或随机数。配置通过有限数值、字符串和布尔值组成的扁平参数对象传入。条件须明确使用布尔值，比较使用严格相等，以保持 JavaScript／Lua 一致。支持局部计算和可从输入推断类型的内部辅助函数。非法函数在构造时拒绝，非法分数使获取失败。两种后端对自定义等待策略的重新评估间隔最多为 200 毫秒。同一 Redis 读写锁 namespace 内的活动请求必须使用相同策略和绕过设置。

callback 会收到 manager，用于改变已有资源的模式：

```ts
await app.rwLock(RWLockMode.READ, ['user', 'quota'], async (manager) => {
  await readUser();
  const upgrade = await manager.upgradeWrite('user');
  if (upgrade.intervenedKeys.includes('user')) await readUser();
  await saveUser();
  await manager.downgradeRead('user');
});
```

`upgradeWrite(keys?)` 和 `downgradeRead(keys?)` 省略 keys 时操作本次 callback 的全部资源，否则只操作指定子集，不允许增加资源。升级先按配置策略尝试原子转换；必须等待时，让出本次事务的全部持锁资源，再以目标资源 WRITE、其他资源保留原模式的组合重新排队获取。自己的旧读权限不会阻挡新请求。降级只把指定资源排队为 READ，其他资源保留；它也可能等待先来的写者。相同模式的转换直接返回。

`upgradeWrite` 返回冻结的 `{ smooth, intervenedKeys }`。每个资源的 WRITE 获取计数会准确找出：从本事务让出到重新拿齐期间，被其他请求以 WRITE 获取过的逻辑 key。单纯让出、等待或其他读者进入都不计入，本事务自己的重新获取也不计入。列表为空时 `smooth` 为 true，即使升级曾经等待过。由于竞争时让出整个持锁范围，列表可能包含没有明确指定升级的其他资源；有插入写者的相关数据需要重新读取。计数只反映遵守 Aragami 锁协议的获取，不追踪锁之外的写入。

必须等转换完成后再访问资源。同一 manager 的转换串行执行，callback 结束时取消未完成转换并释放资源。Redis 等待期间会持续为事务和转换请求续租。仍不支持重入。

Redis 实现保留续租、通知、轮询回退和获取超时异常。manager 的模式转换一直等待到成功，或 callback／driver 结束。

## 队列：把工作交给消费者

队列把「产生工作」和「执行工作」分开。应用可以先放入一封待发送邮件，再由 worker 执行。同一队列上的消费者竞争领取任务，每次领取进入处理中状态，直到确认或恢复。

队列也遵循二层 key。下面的 `jobs` 是模型 namespace，`mail` 是其中的一条队列：

```ts
@CachePrefix('jobs')
class Job { userId!: string; }

await aragami.queueAdd(Job, { userId: 'u1' }, { key: 'mail' });
await aragami.runQueueOnce(Job, (job) => sendMail(job.userId), 'mail');
```

`queueAdd` 支持实例和「类＋对象」两种写法，返回实际入队的实例。可执行任务通常按 FIFO 顺序消费；立即入队时传 `prior: true` 可以放到队首。

`runQueueOnce` 等待一个可执行任务，恢复模型后执行回调。成功时自动确认领取；失败时把该领取的任务重排到队首并抛出异常。如果处理与恢复同时失败，则通过 `AggregateError` 报告两个错误，并保留可恢复的领取。

需要手动领取时，`queueGather` 返回可执行任务或 `undefined`，`queueGatherBlocking` 等待任务出现，两者都会进入处理中状态。`queueResumeAll` 显式恢复处理中任务，保留领取顺序，默认追加到队尾，`prior` 参数可以恢复到队首。恢复需要显式调用，没有自动处理超时。任务 ID 和每次领取的新 token 用来防止旧凭据确认新的领取。

`queueLength`、`queueItems`、`isQueueEmpty` 描述待处理工作：包含尚未到期的任务，不包含处理中任务。列表先显示可执行任务，再按到期时间和入队顺序显示延时任务。`queueClear` 清理待处理工作，保留处理中任务供恢复。

### 延时任务

延时任务是在普通队列任务上指定最早执行时间，适合稍后发送提醒，或在已知时间执行动作。它仍然属于同一条队列，现有消费者就可以处理立即任务和延时任务。

可以使用相对延迟，单位为毫秒，或者绝对时间 `runAt`：

```ts
await aragami.queueAdd(Job, { userId: 'u1' }, { key: 'mail', delay: 5_000 });
await aragami.queueAdd(Job, { userId: 'u2' }, {
  key: 'mail', runAt: new Date(Date.now() + 60_000),
});
```

`delay` 必须为非负有限值；`runAt` 接受有效 Date 或有限的 epoch 毫秒时间戳，两者不能同时指定。过去的时间和零延迟立即可执行。消费者和查询入口负责推进到期任务，不需要额外的调度服务。`prior` 在任务到期进入可执行队列时生效，同批到期任务保持稳定顺序。

Redis 使用服务端时间计算相对延迟和推进到期任务。使用绝对时间时，应用与 Redis 的时钟需要一致。失败重排和恢复不会再次应用原入队延迟。

### 持续消费 worker

`queueSubscribe` 替你执行消费循环：等待任务、处理、确认，然后继续。每个 worker 同时只执行一个回调；需要并行处理时，可以在同一队列上创建多个竞争消费的句柄。

返回的句柄控制 worker 的生命周期：

```ts
const worker = await aragami.queueSubscribe(Job, 'mail', (job) => sendMail(job.userId), {
  retryDelay: 1_000,
  onError: reportError,
});
```

成功后立即继续消费。领取或回调失败时，错误交给 `onError`，未配置时输出日志，然后等待 `retryDelay` 再尝试，默认 **200 毫秒**。失败任务回到队首，错误处理器自身失败也会被捕获。间隔必须非负且有限，`0` 表示不额外等待。

调用 `await worker.unsubscribe()` 停止消费，可以重复调用，并会打断空队列等待和重试等待。已经开始的回调可以完成并得到确认，`await worker.done` 用于等待这段处理结束。回调也可以退订自身，但不能在回调里等待自己的 `done`。省略队列 key 时消费 `default`。

## Pub/Sub：通知每个订阅者

Pub/Sub 把事件广播给主题上的每个活动订阅。用户资料变化后，多个应用模块都需要收到通知，就适合使用广播。每个订阅得到独立恢复的模型实例，一个订阅也可以同时监听同一类 namespace 下的多个 key。

例如，可以把 `User` 模型发布到 `updated` 和 `removed` 主题：

```ts
const sub = await aragami.subscribe(User, ['updated', 'removed'], (message, key) => {
  refreshUserView(message.id, key);
});
await aragami.publish(User, { id: 'u1', name: 'Alice' }, { key: 'updated' });
await sub.unsubscribe();
```

队列的消费者分担工作，Pub/Sub 的各个订阅分别接收匹配的消息。广播采用实时、至多一次交付，不保留历史或补收离线消息，遵循 [Redis Pub/Sub 交付语义](https://redis.io/docs/latest/develop/pubsub/)。Redis database 编号不会隔离频道，不同环境应使用不同广播 prefix。

`publish` 和 `queueAdd` 一样支持两种写法，返回发布的实例，等待发布完成，不等待订阅回调。`subscribe` 把恢复的消息及逻辑 key 交给 handler；省略订阅 key 时监听 `default`。

默认并发执行 handler；`serial: true` 会在当前订阅内按顺序处理，其他订阅仍独立运行。handler 失败交给 `onError`，未配置时只记录错误，不输出消息体。错误处理器自身失败也会被捕获，后续消息继续处理，不重试本条消息。

退订一个句柄不会影响其他订阅，会停止后续分发并丢弃尚未开始的串行回调；已经运行的回调可以结束。返回 Promise 的 Redis 订阅接口会等待频道确认，底层连接共享并按频道引用计数。公共主题与工具内部通知相互隔离。

### 从 RxJS 流发布消息

`publishRx` 把现有 Observable 接到 Pub/Sub。应用中的更新已经通过 RxJS 流转，希望发布结果、错误和结束信号继续留在这条流水线里时，可以使用它。

假设 `updates$` 是用户数据流，发布操作也可以组成一个 Observable：

```ts
const published$ = aragami.publishRx(User, updates$, { key: 'updated' });
const publishing = published$.subscribe({
  next: recordPublication, error: reportError, complete: publicationFinished,
});
```

这是同步方法，返回 **cold Observable**，只有被订阅时才订阅 `updates$`。数据逐条发布，每次成功后推送实际模型实例。source complete 后等待排队中的发布完成，再 complete；source 或发布错误都会进入输出流的 `error`。

需要停止时调用 `publishing.unsubscribe()`，取消 source 并丢弃尚未开始的发布。已经开始的发布可能完成，但不会再推送给已取消的订阅。再次订阅会重新运行 source 并重新发布。

### 用 RxJS 流接收消息

`subscribeRx` 把收到的 Pub/Sub 消息暴露为 cold Observable。需要用 RxJS 操作符过滤、组合或响应事件时，可以直接接入流，而由 Rx 订阅控制生命周期。

传入模型和一个或多个主题 key 即可订阅：

```ts
const receiving = aragami.subscribeRx(User, ['updated', 'removed']).subscribe({
  next: (message) => refreshUserView(message.id),
  error: reportError,
});
```

每次 Rx 订阅独立建立一个实时广播订阅，推送恢复的消息实例，调用 `receiving.unsubscribe()` 可以停止。省略 key 时使用 `default`，这个接口不接受串行或回调 handler 配置。建立订阅和解码失败会使流报错；建立期间取消，也会清理随后返回的句柄。

Redis 建立订阅是异步的，因此 Rx `subscribe` 调用不代表频道已经确认就绪，流里也不会插入就绪消息。如果发布者需要明确等到订阅就绪，应使用返回 Promise 的 `subscribe`。

## 选举与 leader 判定

选举让一组在线成员判断谁应该承担协调工作。例如，多个应用实例都有能力运行定时任务，但应用希望只由当前 leader 负责调度。Aragami 提供成员视图，让应用据此做出决定。

`elect` 是同步方法，返回 **cold `Observable<ElectionState>`**。每次订阅作为独立成员加入，仅调用方法不会加入。第一个状态表示监听和注册完成，之后成员变化时继续推送，直到退订或销毁。

每次推送都是类实例，带有固定的 `selfId`、已排序的 `onlineIds`，以及 `isLeader` 方法：

```ts
const membership = aragami.elect('workers').subscribe((state) => {
  console.log(state.selfId, state.onlineIds);
  updateLeadership(state.isLeader());
});
```

默认把最小的在线 ID 视为 leader。`state.isLeader(2)` 则检查自己是否位于最小的两个在线 ID 中，最多选出两个 leader。其他成员退出不会让自己重新编号。数量必须是非负安全整数，`0` 表示没有 leader。调用 `membership.unsubscribe()` 即可退出这个成员。

`IsLeader` 是对应的 pipe 操作符，`isLeader` 是状态实例的方法。它把成员状态映射为 boolean；只关心领导身份变化时，可以接 `distinctUntilChanged`：

```ts
import { IsLeader } from 'aragami';
import { distinctUntilChanged } from 'rxjs';

const leadership = aragami.elect('workers').pipe(IsLeader(2), distinctUntilChanged())
  .subscribe({ next: updateLeadership, error: reportError });
```

`elect(user)` 使用模型 namespace 和 `LockKey`；`elect()` 与 `elect('default')` 属于同一组。对象上的多个资源 key 会去重、排序，组成一个选举组的身份。异步元数据仅在订阅后解析。

Redis 通过租约、心跳续租、通知和轮询回退跨进程共享成员。租约丢失或到期会使流报错，重新订阅会得到新 ID。每次注册的私有 token 防止旧清理影响新注册；组内序列 key 持久保留，避免 ID 重用。leader 状态描述成员视图，不提供外部写入的 fencing 保护。

内存选举在同一个 driver 内运行：注入相同 driver 的 Aragami 实例共享成员，不同内存 driver 互相隔离。调用 `leadership.unsubscribe()` 同样会退出其选举成员。退订立即停止本地分发和计时器，Redis 退出则异步完成。

## 函数包装与方法装饰器

函数包装器把缓存或锁行为加到已有业务函数上。`useCache`、`useLock`、`useRWLock` 接受业务函数和 key 选择器，调用者就可以复用已经包装好的操作。

对 service 方法，`WrapDecoratorBuilder` 提供 `UseCache`、`UseLock` 和 `UseRWLock`。参数装饰器说明哪些参数提供 key：缓存使用 `WithKey`，两种锁都使用 `WithLockKey`。

因此，一个读取方法可以直接在方法边界声明它的资源：

```ts
import { WithLockKey, WrapDecoratorBuilder } from 'aragami';

const { UseRWLock } = new WrapDecoratorBuilder(() => aragami).build();
class UserService {
  @UseRWLock(RWLockMode.READ)
  async read(@WithLockKey() user: User) { return readUser(user); }
}
```

装饰器保留 `this`、返回值和异常。实例工厂与参数 key 工厂都支持异步，锁参数也可以选择多个资源。

## 配置

配置决定缓存和租约保留多久、锁等待者如何重试，以及物理资源命名空间如何区分。共同的 `lock`、`rwLock`、`pubSub` 配置适用于两种实现，Redis 模式下可由 `redis.lock`、`redis.rwLock`、`redis.pubSub` 覆盖。

主要的 namespace 配置如下：

| 配置 | 默认值 | 用途 |
| --- | --- | --- |
| `defaultTTL` | `0` | 缓存保留时间，单位毫秒；零表示不失效 |
| `redis.lock.prefix` | `_lock` | 普通锁 namespace |
| `redis.rwLock.prefix` | `_rwlock` | 独立的读写锁 namespace |
| `pubSub.prefix` | `_pubsub` | 广播 namespace，可由 `redis.pubSub.prefix` 覆盖 |
| `redis.election.prefix` | `_election` | 选举 namespace |
| `redis.queueKey`、`redis.queueBackupKey` | `_queue`、`_queue_backup` | 待处理和处理中任务的存储 prefix |

`redis.rwLock` 中，`duration` 默认为 **5000 毫秒**，`acquireTimeout` 为 **0**（一直等待），`retryDelay` 为 **200 毫秒**，`retryJitter` 为 **100 毫秒**，`extensionThreshold` 为 **500 毫秒**，最多取租期的一半。`stacked` 默认为 **false**，开启时协调单次获取尝试；策略默认为 **WRITE_FIRST**，`multiKeyBypass` 默认为 **false**。普通 Redis 锁保留独立的时间配置，以及旧的 `retryCount`、`automaticExtensionThreshold` 选项。

`redis.election` 中，`duration` 默认为 **5000 毫秒**，`heartbeatInterval` 为 **duration / 3**，`pollInterval` 为 **1000 毫秒**。时间参数必须是正数且有限，心跳间隔必须小于租期。成员使用不同租期时，共享选举数据按最长活动租期保留。

固定的物理隔离标记让读写锁、广播和选举在 prefix 相同的情况下也与普通锁独立。队列在默认或自定义 prefix 下都使用 `__aragami_queue_v2__` 布局，旧 ready／backup 列表不会被读取、迁移或删除。

## 内存、Redis 与自定义 driver

Redis 是跨进程共享状态的后端；内存实现提供相同 API，适合测试和单进程内的协调工作。

不同能力的共享范围如下：

| 能力 | 内存范围 | Redis 范围 |
| --- | --- | --- |
| 缓存、锁和队列 | 同一个 driver 实例 | 共享 Redis 存储及对应 namespace |
| 选举 | 同一个 driver 实例 | 相同选举 prefix 和资源组 |
| Pub/Sub | 同进程、相同 prefix 和两层 key | 相同服务端频道和 prefix |

`useDriver` 可以注入 `BaseDriver` 子类，优先于 Redis 配置。包导出 `BaseDriver`、`MemoryDriver` 和 `RedisDriver`，支持直接使用。已有 Buffer 队列 driver 可通过兼容适配继续工作，也可以实现基于领取凭据的 claim、确认和恢复方法。内置 Buffer 适配要求确认或恢复时使用领取返回的同一个 Buffer。

实例不再使用时，调用 `await aragami.destroy()`。销毁会停止 worker、complete 活动 Rx 流、等待异步订阅清理，并关闭 driver 资源。阻塞队列操作以 `undefined` 结束，不执行任务回调。Redis 保留未确认工作，重启后可以显式恢复；内存状态则清空。

## 开发与验证

测试覆盖两种后端，包括并发、类恢复、延时任务、取消和资源清理。可以选择完整运行，也可以单独验证一种模式：

| 命令 | 检查内容 |
| --- | --- |
| `npm test` | 完整 memory 和 Redis 测试 |
| `npm run test:memory` | 仅内存，不需要 Docker |
| `npm run test:redis` | 仅 Redis，使用 Compose 测试服务 |
| `ARAGAMI_TEST_REDIS_IMAGE=redis:5.0.0-alpine npm run test:redis` | 最低支持的 Redis 版本 |
| `npm test -- --coverage` | 源码和包入口的覆盖率 |
| `npx tsc --noEmit` | 类型检查 |
| `npm run build` | 构建 CommonJS、原生 ESM 和声明 |
| `npm run test:package` | 已构建 CJS／原生 ESM 包的验收 |

先运行 `npm ci`。项目类型检查和声明构建使用原生 TypeScript 7.0.2；TypeScript 6 兼容 API 用于 TypeScriptToLua、ts-jest 和 lint 工具。构建会通过与自定义 instance 相同的编译器重新生成内置策略 Lua。Redis project 的 TypeScript harness 只管理 `docker compose`，Jest 在宿主机运行；每次使用独立 project 和临时回环端口，启动失败也会清理。测试前自行启动 Docker 运行环境，harness 不依赖 macOS 或 Colima。本开发机使用 Colima，验证后关闭它。给 `tests/package-smoke.mjs` 设置 `ARAGAMI_TEST_REDIS_URI`，即可让两种已构建包格式额外验收 Redis。

## 许可证

Aragami 使用 [MIT 许可证](LICENSE)。
