# Aragami

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

**Aragami is a Redis ORM / Utility for TypeScript**, with corresponding in-memory implementations.

It brings two parts of application development together: storing typed models and coordinating work around them. A class describes the value, its metadata identifies the resource, and Aragami handles serialization, class restoration and the Redis operations behind caching, locks, queues, broadcasting and election.

The same model can be cached by user ID, protected during an update, or published as a message. Each capability has its own storage namespace, while the application keeps the same **class namespace + your own key** design.

| What your application needs | What Aragami provides |
| --- | --- |
| Reuse a loaded profile or computed result | Typed caching, TTL and cache-aside loading |
| Coordinate access to shared resources | Exclusive locks and read/write locks |
| Move work into background consumers | Acknowledged queues and continuous workers |
| Make work available at a later time | Delayed jobs in the same queue |
| Notify every interested subscriber | Live Pub/Sub, with callback and RxJS APIs |
| Choose one or several active coordinators | Election snapshots and leader selection |

## Name & philosophy

**Aragami** takes its name from **Aragami**, a song by the composer **xi**.

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

The library keeps resource identity close to the model, and provides the same operations as your application moves from local memory to shared Redis state.

## Getting started

Install the package in your application:

```sh
npm install aragami
```

Create an Aragami instance with a Redis connection to share state across application processes:

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

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

Calling `new Aragami()` instead uses memory. This is useful for local development and tests that need the same public APIs without a Redis server. The scope of shared state differs between the backends; the [driver section](#memory-redis-and-custom-drivers) explains those boundaries.

The package provides CommonJS, native ESM and TypeScript declarations, and loads `reflect-metadata` through its entry point. For the decorator examples below, enable `experimentalDecorators` and `emitDecoratorMetadata` in TypeScript's `compilerOptions`.

Redis mode supports **Redis 5.0.0 or newer**, with Lua scripting and Pub/Sub enabled. The complete Redis suite and built CJS/native ESM packages have been verified against **5.0.0** and **7.4.9**. Queue, read/write lock and election scripts combine Redis `TIME` with writes, relying on [script effects replication, enabled by default since Redis 5.0](https://redis.io/docs/latest/develop/programmability/eval-intro/#replicating-commands-instead-of-scripts).

The Rx APIs use **RxJS `^7.8.2`**, compatible with the `^7.1.0` peer range declared by [NestJS 12](https://github.com/nestjs/nest/blob/v12.1.2/packages/core/package.json).

## One model, two key layers

Aragami organizes resources around classes. The first key layer is the class namespace: `@CachePrefix` supplies it, or the class name is used. The second layer identifies a particular value, queue, topic or resource within that namespace.

For example, a user model can belong to `users`, with its ID supplying the individual key:

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

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

Here, `CacheKey` gives cache entries their identity, and `LockKey` identifies the resource used by locking and election. This example makes both use the ID itself. Without a factory, `@LockKey()` produces `fieldName_fieldValue`, such as `id_u1`. Key decorators also work with methods, getters and asynchronous factories.

An explicit key overrides `CacheKey`. Queue insertion and message publication use `CacheKey` when available, then fall back to `default`; queue consumer/query methods and message subscriptions use the supplied key, or the literal `default`. Locks also accept strings as direct resource keys. Election accepts a string, an object, or no argument; objects without `LockKey` use their class namespace plus `default`.

Cache entries, exclusive locks, read/write locks, queues, Pub/Sub and election remain independent even when their logical keys match. You can use the same model across these features without merging their state. The examples below reuse `aragami` and `User` from this introduction.

## Typed caching and class restoration

A cache saves values that are expensive to load or calculate. Aragami adds a model layer to that operation: reading a cached `User` restores a `User` instance, so application code can keep working with its class rather than manually rebuilding it after every read.

Use `set` to store an instance or a class plus an object, and `get` to load by class and 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 });
```

The returned values are model instances; a missing cache entry returns `undefined`. `@CastType(() => Child)` describes nested models, including array elements, and `@CastType(() => Date)` restores date fields. This mapping between classes, keys and serialized values is the ORM part of Aragami.

TTL controls how long a value remains cached, in milliseconds. An explicit `ttl` takes precedence over the model's `@CacheTTL`, then `defaultTTL`; the final default is `0`, meaning no expiry. Explicit keys, including an empty string, override model metadata.

For inspection and cleanup, `has` checks existence, `del` removes an entry, and `keys`, `values` and `entries` enumerate a class namespace. `clear` removes entries from that namespace. The listing and clearing methods accept a literal key prefix, making it possible to work with one family of cached values.

### Load on a cache miss

Cache-aside loading combines lookup and population. `cache` returns the cached model when present; otherwise it calls your loader and stores the result. This fits operations such as fetching a profile from a database or another service:

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

An empty or missing source key bypasses caching, and null/undefined loader results are not stored. `useCache` wraps a loader with the same behavior when you want a reusable function rather than a separate `cache` call at each use.

## Exclusive locks

An exclusive lock lets one operation at a time work on a resource. It is useful when two requests might update the same user, or when several processes need to coordinate a shared operation. Aragami derives object resources from `LockKey`, so the identity can stay next to the model.

The callback runs after the lock is acquired, and its completion releases the lock:

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

You can also pass a string key or an array of objects and strings. A multi-resource lock deduplicates repeated keys and runs immediately for an empty array. Synchronous and asynchronous callbacks preserve their return values and exceptions. `useLock` applies the same behavior to a reusable function.

Redis locks use leases that renew while the callback is running, with release notifications and polling to wake waiters. Acquisition timeouts throw `LockAcquireTimeoutError`. A long process pause or Redis outage can still expire a lease; the callback is not forcibly cancelled, and external writes are not fenced.

`lock.multiKeyBypass` defaults to `false`. Enable it for local all-or-nothing acquisition so a request waiting for B does not reserve A. `redis.lock.multiKeyBypass` overrides the common setting. With Redis `stacked` enabled, bypass limits local coordination to individual acquisition attempts; Redis itself always acquires all keys atomically. Ordinary and read/write locks retain independent state.

## Read/write locks

A read/write lock allows several readers to share a resource while keeping writers exclusive. Use it when reads can safely overlap, but a change must wait for current readers and prevent overlapping reads or writes while it runs.

The first argument is `RWLockMode`, an exported TypeScript enum with `READ` and `WRITE` members:

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

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

Read/write locks use the same object metadata and multi-resource rules as exclusive locks, but have an independent physical namespace and configuration. `isRWFree(mode, resource)` checks whether that mode can enter; `useRWLock` wraps a function.

The default strategy is `RWLockPriority.WRITE_FIRST`. Choose `READ_FIRST` to favor waiting readers, or `FIFO` to order conflicting requests by first registration. Readers can overlap, unrelated keys can proceed, and held locks are never preempted. The deprecated `writerPriority` setting is only consulted when `writerPriorityStrategy` is absent.

```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` and `FifoRWLockPriorityStrategy` are exported drivers. They score readers/writers as `1/0`, `0/1` and `0/0` respectively. Higher scores enter first; equal scores use FIFO for conflicting requests.

`rwLock.multiKeyBypass` defaults to `false`: a waiting request for `[A, B]` can also block A while B is held. Enable it to let A's requests pass when the earlier waiter is blocked by an incompatible holder on B. This exception only checks actual holders on keys outside the candidate's resources. `isRWFree` observes the same rules with a prospective request of age zero.

Custom drivers use a synchronous pure function, compiled to Redis-compatible Lua when the instance is constructed:

```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,
  },
});
```

The function receives a read-only request (`id`, `mode`, deduplicated logical `keys`, `enqueuedAt`, `waitedMs`, `sequence`) and context (`now`, the complete ordered `waiting` snapshot including the current request, and fixed `params`). Times are milliseconds. It must return a finite number; negative and fractional scores are valid, and zero is a priority rather than a rejection or delay. `getPriority(request, state)` evaluates the same function locally. `params`, `luaSource` and `fingerprint` are read-only; reuse the instance without recompilation.

Functions cannot capture external variables, use `this`, imports, async code, I/O, clocks or randomness. Pass configuration as a flat record of finite numbers, strings and booleans. Use explicit boolean conditions and strict equality so JavaScript and Lua agree. Local computations and helpers whose types can be inferred from the inputs are supported. Invalid functions fail at construction; invalid scores fail acquisition. Custom waiters are reevaluated at most every 200 milliseconds in both backends. Active requests sharing a Redis rw namespace must use the same strategy and bypass setting.

The callback receives a manager for changing existing resources:

```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?)` and `downgradeRead(keys?)` apply to all callback resources when keys are omitted, or a selected subset otherwise; new resources cannot be added. An upgrade first tries an atomic conversion under the configured priority policy. If it must wait, it yields the entire transaction's held resources and requeues the full scope with the requested resources in WRITE mode and all other resources in their original modes. Its own old read rights cannot block the new request. A downgrade queues the selected resources in READ mode while keeping other resources held, and may wait behind an earlier writer. No-op conversions return immediately.

`upgradeWrite` returns a frozen `{ smooth, intervenedKeys }`. Per-resource WRITE-acquisition counters identify exactly which logical keys another request acquired in WRITE mode after this transaction yielded and before it reacquired them. Merely yielding, waiting or admitting another reader does not count; the transaction's own reacquisition is excluded. `smooth` is true exactly when that list is empty, even if the upgrade waited. The list may include resources outside the explicitly upgraded subset because the fallback yields the whole scope. Re-read affected data after an intervening writer. These counters track cooperative lock acquisitions, not writes made outside Aragami.

Await each conversion before accessing the resources. Conversions on one manager are serialized; callback completion cancels unfinished conversions and releases its resources. Redis continues renewing the transaction and its queued conversion while waiting. Reentry remains unsupported.

Redis read/write locks retain lease renewal, notifications, polling fallback and acquisition-timeout errors. A manager conversion waits until granted or until its callback/driver ends.

## Queues: work for a consumer

A queue separates creating work from executing it. An application can enqueue a mail request immediately, then let a worker handle it later. Consumers on the same queue compete for jobs, and each claim enters a processing state until acknowledged or recovered.

Queues also follow the two key layers. In this example, `jobs` is the model namespace and `mail` is the queue within it:

```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` accepts an instance or a class plus an object and returns the actual enqueued instance. Ready jobs normally follow FIFO order; `prior: true` inserts an immediate job at the front.

`runQueueOnce` waits for one executable job, restores the model and invokes your callback. Success automatically acknowledges the claim. Failure requeues that claim at the front and rethrows the error; if both processing and recovery fail, `AggregateError` reports both errors and leaves the claim recoverable.

For manual claiming, `queueGather` returns an executable job or `undefined`, while `queueGatherBlocking` waits for one. Both enter processing state. `queueResumeAll` explicitly restores processing jobs, preserving claim order and appending by default; its `prior` argument restores them to the front. Recovery is explicit, with no automatic processing timeout. Distinct task IDs and fresh claim tokens prevent an old receipt from acknowledging a later claim.

`queueLength`, `queueItems` and `isQueueEmpty` describe pending work, including future delayed jobs and excluding processing claims. Items show ready jobs first, followed by delayed jobs in due-time and insertion order. `queueClear` removes pending work and preserves processing claims for recovery.

### Delayed jobs

A delayed job is ordinary queued work with an earliest execution time. This is useful for sending a reminder later or scheduling an action at a known time. It stays in the same queue, so existing consumers can handle immediate and delayed jobs together.

Choose a relative delay in milliseconds or an absolute `runAt` time:

```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` must be nonnegative and finite. `runAt` accepts a valid Date or finite epoch-millisecond timestamp; the two options cannot be combined. Past times and zero delays are immediately executable. Consumers and queries promote due jobs, so no separate scheduler service is required. `prior` takes effect when a delayed job becomes ready, preserving stable order within each due batch.

Redis uses server time for relative delays and promotion. Absolute times require application and Redis clocks to agree. Retry and recovery do not apply the original delay again.

### Continuous workers

`queueSubscribe` runs the consume loop for you: wait for work, process it, acknowledge it, and continue. Each worker runs one callback at a time. Create several handles on the same queue when you want competing consumers to process jobs in parallel.

The returned handle controls the worker's lifetime:

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

Successful processing continues immediately. A failed claim or callback is reported through `onError`, or logged when no handler is supplied, then retried after `retryDelay` (default **200 ms**). Failed jobs return to the front. Error-handler failures are caught. The interval must be nonnegative and finite; `0` adds no retry wait.

Call `await worker.unsubscribe()` to stop consumption; it is idempotent and interrupts idle or retry waits. An already running callback may finish and be acknowledged; `await worker.done` lets the caller wait for that drain. A callback can unsubscribe its own worker, but should not await its own `done`. Omitting the queue key consumes `default`.

## Pub/Sub: messages for every subscriber

Pub/Sub broadcasts an event to every active subscription on its topic. It suits notifications such as a user update that several parts of an application need to observe. Each subscriber gets its own restored model instance, and a subscription can listen to several keys within one class namespace.

For example, the `User` model can be broadcast on the `updated` and `removed` topics:

```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();
```

Queue consumers share work; Pub/Sub subscriptions each receive matching messages. Broadcasting is live and at most once, with no history or offline replay, following [Redis Pub/Sub delivery semantics](https://redis.io/docs/latest/develop/pubsub/). Redis database numbers do not separate channels, so use different Pub/Sub prefixes for different environments.

`publish` accepts either publishing form used by `queueAdd`, returns the published instance, and waits for publication rather than subscriber callbacks. `subscribe` passes the restored message and logical key to its handler. An omitted subscription key listens to `default`.

Handlers run concurrently by default. `serial: true` processes messages in order within that subscription while other subscriptions remain independent. Handler failures go to `onError`, or are logged without the message body; error-handler failures are caught and later messages continue without retry.

Unsubscribing one handle preserves other subscriptions, stops future delivery and discards queued serial callbacks. Running callbacks can finish. The Promise-based Redis subscription returns after channel acknowledgment, using a shared connection with channel reference counts. Public topics are isolated from internal utility notifications.

### Publishing from an RxJS stream

`publishRx` connects an existing Observable to Pub/Sub. It is useful when updates already flow through RxJS and you want publication results, errors and completion to remain in that pipeline.

Given an `updates$` stream of user values, publication can become another Observable:

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

This is a synchronous method returning a **cold Observable**: it subscribes to `updates$` only when subscribed. Values publish sequentially, with each successful publication emitting the actual model instance. Source completion waits for queued publications; source or publication errors reach the output's `error` channel.

Call `publishing.unsubscribe()` when stopping. This detaches the source and discards unstarted publications. An already started publication may finish, but cannot emit to the cancelled subscription. Subscribing again runs the source and publications again.

### Receiving messages as an RxJS stream

`subscribeRx` exposes incoming Pub/Sub messages as a cold Observable. It fits applications that want to filter, combine or react to events with RxJS operators instead of managing a callback subscription handle.

Subscribe by model and one or more topic keys:

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

Each Rx subscription owns an independent live subscription and emits restored messages. Call `receiving.unsubscribe()` to stop it. Omitted keys use `default`; serial and callback-handler options are not part of this API. Setup and decoding failures error the stream. Cancellation during setup also cleans up the eventual handle.

Redis setup is asynchronous, so the Rx `subscribe` call is not a channel-ready acknowledgment, and the stream does not inject a readiness message. Use the Promise-based `subscribe` when a publisher needs to wait explicitly for its subscriber to be ready.

## Election and leader selection

Election lets a group of active participants agree which members should act as coordinators. For example, several application instances may be able to run a periodic task, while only the current leader should schedule it. Aragami exposes the membership view so the application can make that decision.

`elect` is a synchronous method returning a **cold `Observable<ElectionState>`**. Every subscription joins as a separate participant; calling the method alone joins nothing. The first snapshot means listening and registration have finished, and later snapshots describe membership changes until unsubscribe or destruction.

Each snapshot is a class instance with a fixed `selfId`, sorted `onlineIds`, and an `isLeader` method:

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

The smallest online ID is the leader by default. `state.isLeader(2)` selects up to two leaders by checking whether this participant is among the two smallest online IDs. Leaving members do not renumber survivors. Counts must be nonnegative safe integers; zero selects no leaders. Call `membership.unsubscribe()` to withdraw this participant.

`IsLeader` is the corresponding pipe operator, while `isLeader` belongs to the snapshot. It maps membership to a boolean; use `distinctUntilChanged` if only leadership transitions matter:

```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)` uses the model's namespace and `LockKey`; `elect()` uses the same group as `elect('default')`. An object's multiple resource keys form one deduplicated, sorted group identity. Asynchronous metadata resolves only after subscription.

Redis shares membership across processes using leases, heartbeat renewal, notifications and polling fallback. A lost or expired lease errors the stream; a new subscription gets a new ID. Registrations have private tokens to protect against stale cleanup, and per-group sequence keys persist to prevent ID reuse. Leader snapshots describe membership and do not fence external writes.

Memory elections run within one driver instance. Facades injecting that same driver share membership; separate memory drivers have separate elections. Calling `leadership.unsubscribe()` also withdraws its participant. Unsubscribe immediately stops local delivery and timers, while Redis removal finishes asynchronously.

## Function wrappers and method decorators

Wrappers apply cache or lock behavior to functions that already express your business operation. `useCache`, `useLock` and `useRWLock` take a key selector alongside the function, letting callers reuse the wrapped operation without repeating resource selection.

For service methods, `WrapDecoratorBuilder` supplies `UseCache`, `UseLock` and `UseRWLock`. Parameter decorators identify which arguments provide keys: `WithKey` for caching and `WithLockKey` for both lock types.

A read method can therefore declare its resource at the method boundary:

```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); }
}
```

Decorators preserve `this`, return values and exceptions. Instance factories and parameter key factories may be asynchronous; lock parameters may select several resources.

## Configuration

Configuration controls how long cached data or leases live, how lock waiters retry, and how physical resource namespaces are separated. Common `lock`, `rwLock` and `pubSub` settings apply to both implementations; `redis.lock`, `redis.rwLock` and `redis.pubSub` override them in Redis mode.

The main namespace settings are:

| Setting | Default | Purpose |
| --- | --- | --- |
| `defaultTTL` | `0` | Cache lifetime in milliseconds; zero means no expiry |
| `redis.lock.prefix` | `_lock` | Ordinary lock namespace |
| `redis.rwLock.prefix` | `_rwlock` | Independent read/write lock namespace |
| `pubSub.prefix` | `_pubsub` | Broadcast namespace; overridable by `redis.pubSub.prefix` |
| `redis.election.prefix` | `_election` | Election namespace |
| `redis.queueKey`, `redis.queueBackupKey` | `_queue`, `_queue_backup` | Pending and processing queue storage prefixes |

For `redis.rwLock`, `duration` defaults to **5000 ms**, `acquireTimeout` to **0** (wait indefinitely), `retryDelay` to **200 ms**, `retryJitter` to **100 ms**, and `extensionThreshold` to **500 ms**, capped at half the lease. `stacked` defaults to **false** and coordinates individual acquisition attempts. The strategy defaults to **WRITE_FIRST** and `multiKeyBypass` to **false**. Ordinary Redis locks have their own timing configuration and retain the legacy `retryCount` and `automaticExtensionThreshold` options.

For `redis.election`, `duration` defaults to **5000 ms**, `heartbeatInterval` to **duration / 3**, and `pollInterval` to **1000 ms**. Intervals must be positive and finite, with the heartbeat interval shorter than the lease. Shared election data is retained for the longest active lease when participants use different durations.

Physical isolation markers keep read/write locks, broadcasting and election separate from ordinary locks even when prefixes match. The queue layout uses `__aragami_queue_v2__` with default or custom prefixes; old ready/backup lists are not read, migrated or deleted.

## Memory, Redis and custom drivers

Redis is the shared backend for applications running across processes. Memory implements the same APIs with local state, and is especially useful for tests or applications that need coordination within a single process.

The sharing boundaries are deliberate:

| Capability | Memory scope | Redis scope |
| --- | --- | --- |
| Cache, locks and queues | One driver instance | Shared Redis storage and configured namespaces |
| Election | One driver instance | Shared election prefix and resource group |
| Pub/Sub | Same process, prefix and both key layers | Shared server channels and prefix |

`useDriver` injects a `BaseDriver` subclass and takes precedence over Redis configuration. `BaseDriver`, `MemoryDriver` and `RedisDriver` are exported for direct use. Existing Buffer-based queue drivers remain supported through compatibility adapters; drivers can also implement the receipt-based claim, acknowledgment and recovery methods. Built-in Buffer adapters require the exact Buffer returned by gathering a job.

Call `await aragami.destroy()` when the instance is no longer needed. Destruction stops its workers, completes active Rx streams, drains asynchronous subscription cleanup and closes driver resources. Blocking queue operations finish with `undefined` without calling job callbacks. Redis retains unacknowledged work for explicit recovery after restart; memory state is cleared.

## Development and verification

The test suite exercises both backends, including concurrency, class restoration, delayed work, cancellation and resource cleanup. Choose the complete run or an individual backend as needed:

| Command | What it checks |
| --- | --- |
| `npm test` | Complete memory and Redis suites |
| `npm run test:memory` | Memory only; no Docker required |
| `npm run test:redis` | Redis with a Compose-managed test service |
| `ARAGAMI_TEST_REDIS_IMAGE=redis:5.0.0-alpine npm run test:redis` | Minimum supported Redis version |
| `npm test -- --coverage` | Coverage for source and the package entry |
| `npx tsc --noEmit` | Type checking |
| `npm run build` | CommonJS, native ESM and declarations |
| `npm run test:package` | Built CJS/native ESM package smoke checks |

Run `npm ci` first. Project checking and declarations use native TypeScript 7.0.2; the TypeScript 6 compatibility API supports TypeScriptToLua, ts-jest and lint tooling. Builds regenerate the built-in strategy Lua through the same compiler used by custom instances. The Redis project's TypeScript harness manages only `docker compose`: Jest runs on the host, each run gets a unique project and ephemeral loopback port, and startup failures also trigger cleanup. Start your Docker runtime beforehand; the harness has no macOS or Colima dependency. This development machine uses Colima and stops it after verification. Setting `ARAGAMI_TEST_REDIS_URI` for `tests/package-smoke.mjs` adds Redis checks to both built formats.

## License

Aragami is released under the [MIT license](LICENSE).
