zeitlich 0.2.49 → 0.2.51

package/src/lib/thread/manager.test.ts

@@ -1,45 +1,53 @@
 import { describe, expect, it, beforeEach } from "vitest";
-import type Redis from "ioredis";
+import type { RedisClientType } from "redis";
 import { createThreadManager } from "./manager";
 import type { PersistedThreadState } from "../state/types";
 
+type Keys = string | string[];
+const toKeys = (keys: Keys): string[] => (Array.isArray(keys) ? keys : [keys]);
+
 /**
- * Minimal in-memory Redis stub exposing just the commands used by
+ * Minimal in-memory node-redis stub exposing just the commands used by
  * `createThreadManager`'s state methods (get/set/del/exists/expire) plus
- * the list helpers needed for `initialize`.
+ * the list helpers needed for `initialize`/`fork`. Uses the node-redis
+ * (`redis`) camelCase API and array-or-variadic keys.
  */
-function createFakeRedis(): Redis {
+function createFakeRedis(): RedisClientType {
   const store = new Map<string, string>();
 
   const redis = {
     async get(key: string): Promise<string | null> {
       return store.has(key) ? (store.get(key) as string) : null;
     },
-    async set(key: string, value: string): Promise<"OK"> {
+    async set(
+      key: string,
+      value: string,
+      _options?: { EX?: number }
+    ): Promise<"OK"> {
       store.set(key, String(value));
       return "OK";
     },
-    async del(...keys: string[]): Promise<number> {
+    async del(keys: Keys): Promise<number> {
       let removed = 0;
-      for (const k of keys) {
+      for (const k of toKeys(keys)) {
         if (store.delete(k)) removed++;
       }
       return removed;
     },
-    async exists(...keys: string[]): Promise<number> {
-      return keys.reduce((acc, k) => acc + (store.has(k) ? 1 : 0), 0);
+    async exists(keys: Keys): Promise<number> {
+      return toKeys(keys).reduce((acc, k) => acc + (store.has(k) ? 1 : 0), 0);
     },
     async expire(_key: string, _ttl: number): Promise<number> {
       return 1;
     },
-    async lrange(): Promise<string[]> {
+    async lRange(): Promise<string[]> {
       return [];
     },
-    async rpush(): Promise<number> {
+    async rPush(): Promise<number> {
       return 0;
     },
     _store: store,
-  } as unknown as Redis & { _store: Map<string, string> };
+  } as unknown as RedisClientType & { _store: Map<string, string> };
 
   return redis;
 }
@@ -64,10 +72,12 @@ const baseSlice: PersistedThreadState = {
 };
 
 describe("createThreadManager state persistence", () => {
-  let redis: Redis & { _store: Map<string, string> };
+  let redis: RedisClientType & { _store: Map<string, string> };
 
   beforeEach(() => {
-    redis = createFakeRedis() as Redis & { _store: Map<string, string> };
+    redis = createFakeRedis() as RedisClientType & {
+      _store: Map<string, string>;
+    };
   });
 
   async function initThread(threadId: string): Promise<void> {

package/src/lib/thread/manager.ts

@@ -60,12 +60,12 @@ export function createThreadManager<T>(
   return {
     async initialize(): Promise<void> {
       await redis.del(redisKey);
-      await redis.set(metaKey, "1", "EX", ttlSeconds);
+      await redis.set(metaKey, "1", { EX: ttlSeconds });
     },
 
     async load(): Promise<T[]> {
       await assertThreadExists();
-      const data = await redis.lrange(redisKey, 0, -1);
+      const data = await redis.lRange(redisKey, 0, -1);
       return data.map(deserialize);
     },
 
@@ -75,23 +75,19 @@ export function createThreadManager<T>(
 
       if (idOf) {
         const dedupId = messages.map(idOf).join(":");
-        await redis.eval(
-          APPEND_IDEMPOTENT_SCRIPT,
-          2,
-          dedupKey(dedupId),
-          redisKey,
-          String(ttlSeconds),
-          ...messages.map(serialize)
-        );
+        await redis.eval(APPEND_IDEMPOTENT_SCRIPT, {
+          keys: [dedupKey(dedupId), redisKey],
+          arguments: [String(ttlSeconds), ...messages.map(serialize)],
+        });
       } else {
-        await redis.rpush(redisKey, ...messages.map(serialize));
+        await redis.rPush(redisKey, messages.map(serialize));
         await redis.expire(redisKey, ttlSeconds);
       }
     },
 
     async fork(newThreadId: string): Promise<BaseThreadManager<T>> {
       await assertThreadExists();
-      const data = await redis.lrange(redisKey, 0, -1);
+      const data = await redis.lRange(redisKey, 0, -1);
       const stateRaw = await redis.get(stateKey);
       const forked = createThreadManager({
         ...config,
@@ -100,12 +96,12 @@ export function createThreadManager<T>(
       await forked.initialize();
       if (data.length > 0) {
         const newKey = getThreadListKey(key, newThreadId);
-        await redis.rpush(newKey, ...data);
+        await redis.rPush(newKey, data);
         await redis.expire(newKey, ttlSeconds);
       }
       if (stateRaw != null) {
         const newStateKey = getThreadStateKey(key, newThreadId);
-        await redis.set(newStateKey, stateRaw, "EX", ttlSeconds);
+        await redis.set(newStateKey, stateRaw, { EX: ttlSeconds });
       }
       return forked;
     },
@@ -117,23 +113,23 @@ export function createThreadManager<T>(
           "replaceAll requires the thread manager to be configured with `idOf`"
         );
       }
-      const existing = await redis.lrange(redisKey, 0, -1);
+      const existing = await redis.lRange(redisKey, 0, -1);
       const existingIds = existing
         .map((raw) => idOf(deserialize(raw)))
         .filter((id): id is string => typeof id === "string");
       await redis.del(redisKey);
       if (existingIds.length > 0) {
-        await redis.del(...existingIds.map(dedupKey));
+        await redis.del(existingIds.map(dedupKey));
       }
       if (messages.length > 0) {
-        await redis.rpush(redisKey, ...messages.map(serialize));
+        await redis.rPush(redisKey, messages.map(serialize));
         await redis.expire(redisKey, ttlSeconds);
       }
       await redis.expire(metaKey, ttlSeconds);
     },
 
     async delete(): Promise<void> {
-      await redis.del(redisKey, metaKey, stateKey);
+      await redis.del([redisKey, metaKey, stateKey]);
     },
 
     async loadState(): Promise<PersistedThreadState | null> {
@@ -144,7 +140,7 @@ export function createThreadManager<T>(
 
     async saveState(state: PersistedThreadState): Promise<void> {
       await assertThreadExists();
-      await redis.set(stateKey, JSON.stringify(state), "EX", ttlSeconds);
+      await redis.set(stateKey, JSON.stringify(state), { EX: ttlSeconds });
     },
 
     async deleteState(): Promise<void> {
@@ -153,7 +149,7 @@ export function createThreadManager<T>(
 
     async length(): Promise<number> {
       await assertThreadExists();
-      return redis.llen(redisKey);
+      return redis.lLen(redisKey);
     },
 
     async truncateFromId(messageId: string): Promise<void> {
@@ -163,7 +159,7 @@ export function createThreadManager<T>(
           "truncateFromId requires the thread manager to be configured with `idOf`"
         );
       }
-      const data = await redis.lrange(redisKey, 0, -1);
+      const data = await redis.lRange(redisKey, 0, -1);
       let idx = -1;
       const removedIds: string[] = [];
       for (let i = 0; i < data.length; i++) {
@@ -178,7 +174,7 @@ export function createThreadManager<T>(
         await redis.del(redisKey);
         await redis.expire(metaKey, ttlSeconds);
       } else {
-        await redis.ltrim(redisKey, 0, idx - 1);
+        await redis.lTrim(redisKey, 0, idx - 1);
         await redis.expire(redisKey, ttlSeconds);
       }
       // Clear dedup markers for the removed messages so that a rewind
@@ -186,7 +182,7 @@ export function createThreadManager<T>(
       // re-append without the idempotent-append Lua script treating it
       // as a duplicate.
       if (removedIds.length > 0) {
-        await redis.del(...removedIds.map(dedupKey));
+        await redis.del(removedIds.map(dedupKey));
       }
     },
   };

package/src/lib/thread/snapshot.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, beforeEach } from "vitest";
-import type Redis from "ioredis";
+import type { RedisClientType } from "redis";
 import {
   applySnapshot,
   clearHotTier,
@@ -14,7 +14,7 @@ import {
 } from "./keys";
 import type { PersistedThreadState } from "../state/types";
 import type { ThreadSnapshot } from "./cold-store";
-import { createFakeRedis } from "./test-utils";
+import { createFakeRedis, makeMultiError } from "./test-utils";
 
 const sampleState: PersistedThreadState = {
   tasks: [
@@ -36,7 +36,7 @@ const sampleState: PersistedThreadState = {
 };
 
 describe("encodeSnapshot", () => {
-  let redis: Redis & { _store: Map<string, unknown> };
+  let redis: RedisClientType & { _store: Map<string, unknown> };
 
   beforeEach(() => {
     redis = createFakeRedis();
@@ -97,7 +97,7 @@ describe("encodeSnapshot", () => {
 });
 
 describe("applySnapshot", () => {
-  let redis: Redis & { _store: Map<string, unknown> };
+  let redis: RedisClientType & { _store: Map<string, unknown> };
 
   beforeEach(() => {
     redis = createFakeRedis();
@@ -178,7 +178,7 @@ describe("applySnapshot", () => {
     const metaKey = getThreadMetaKey("messages", "t-1");
     expect(await redis.exists(metaKey)).toBe(1);
     expect(
-      await redis.lrange(getThreadListKey("messages", "t-1"), 0, -1)
+      await redis.lRange(getThreadListKey("messages", "t-1"), 0, -1)
     ).toEqual([]);
   });
 
@@ -190,7 +190,7 @@ describe("applySnapshot", () => {
     const wrapped = new Proxy(redis, {
       get(target, prop, receiver): unknown {
         if (prop === "del") {
-          return async (..._keys: string[]): Promise<number> => {
+          return async (_keys: string | string[]): Promise<number> => {
             throw new Error("NOPERM: DEL denied by ACL");
           };
         }
@@ -206,7 +206,7 @@ describe("applySnapshot", () => {
     };
     await expect(
       applySnapshot({
-        redis: wrapped as unknown as Redis,
+        redis: wrapped as unknown as RedisClientType,
         threadKey: "messages",
         threadId: "t-del-fail",
         snapshot: snap,
@@ -230,42 +230,44 @@ describe("applySnapshot", () => {
   });
 
   it("clears list/state/dedup residue when a pipelined write fails partway", async () => {
-    // Pipeline stub that *applies* non-failing commands to the
-    // underlying fake (so residue is observable) and errors on rpush
+    // `multi()` stub that *applies* non-failing commands to the
+    // underlying fake (so residue is observable) and errors on rPush
     // — mimicking a partial OOM where the list write fails but the
     // dedup SETs queued after it still land. Without compensating
     // cleanup, those stale dedup keys could silently skip a future
-    // append with the same id.
+    // append with the same id. node-redis rejects `execAsPipeline`
+    // with a `MultiErrorReply` carrying per-command errors.
     const wrapped = new Proxy(redis, {
       get(target, prop, receiver): unknown {
-        if (prop === "pipeline") {
+        if (prop === "multi") {
           return (): Record<string, unknown> => {
             type Op = { method: string; args: unknown[] };
             const ops: Op[] = [];
             const chain: Record<string, unknown> = {};
-            for (const m of ["set", "del", "rpush", "expire"]) {
+            for (const m of ["set", "del", "rPush", "expire"]) {
               chain[m] = (...args: unknown[]): Record<string, unknown> => {
                 ops.push({ method: m, args });
                 return chain;
               };
             }
-            chain.exec = async (): Promise<Array<[Error | null, unknown]>> => {
-              const out: Array<[Error | null, unknown]> = [];
+            chain.execAsPipeline = async (): Promise<unknown[]> => {
+              const replies: unknown[] = [];
+              const errorIndexes: number[] = [];
               const callable = target as unknown as Record<
                 string,
                 (...a: unknown[]) => Promise<unknown>
               >;
-              for (const op of ops) {
-                if (op.method === "rpush") {
-                  out.push([new Error("OOM"), null]);
+              for (const [i, op] of ops.entries()) {
+                if (op.method === "rPush") {
+                  replies.push(new Error("OOM"));
+                  errorIndexes.push(i);
                   continue;
                 }
                 const fn = callable[op.method];
                 if (!fn) throw new Error(`stub: unknown ${op.method}`);
-                const result = await fn(...op.args);
-                out.push([null, result]);
+                replies.push(await fn(...op.args));
               }
-              return out;
+              throw makeMultiError(replies, errorIndexes);
             };
             return chain;
           };
@@ -282,7 +284,7 @@ describe("applySnapshot", () => {
     };
     await expect(
       applySnapshot({
-        redis: wrapped as unknown as Redis,
+        redis: wrapped as unknown as RedisClientType,
         threadKey: "messages",
         threadId: "t-residue",
         snapshot: snap,
@@ -305,30 +307,36 @@ describe("applySnapshot", () => {
   });
 
   it("throws and leaves the meta key unset when a pipelined command fails", async () => {
-    // Wrap the fake's `pipeline()` so `exec()` returns a tuple list
-    // containing a per-command error — mimicking ioredis's behaviour
-    // when Redis runtime errors (OOM, ACL, WRONGTYPE) occur inside a
-    // pipeline. The top-level promise resolves; the error lives in the
-    // result tuple, and applySnapshot must surface it.
+    // Wrap the fake's `multi()` so `execAsPipeline()` rejects with a
+    // `MultiErrorReply` — mimicking node-redis's behaviour when Redis
+    // runtime errors (OOM, ACL, WRONGTYPE) occur inside a pipeline.
+    // `applySnapshot` must surface the underlying error.
     const wrapped = new Proxy(redis, {
       get(target, prop, receiver): unknown {
-        if (prop === "pipeline") {
+        if (prop === "multi") {
           return (): Record<string, unknown> => {
             type Op = { method: string; args: unknown[] };
             const ops: Op[] = [];
             const chain: Record<string, unknown> = {};
-            for (const m of ["set", "del", "rpush", "expire"]) {
+            for (const m of ["set", "del", "rPush", "expire"]) {
               chain[m] = (...args: unknown[]): Record<string, unknown> => {
                 ops.push({ method: m, args });
                 return chain;
               };
             }
-            chain.exec = async (): Promise<Array<[Error | null, unknown]>> =>
-              ops.map((op, i) =>
-                op.method === "rpush"
-                  ? [new Error("OOM command not allowed"), null]
-                  : [null, i]
-              );
+            chain.execAsPipeline = async (): Promise<unknown[]> => {
+              const replies: unknown[] = [];
+              const errorIndexes: number[] = [];
+              ops.forEach((op, i) => {
+                if (op.method === "rPush") {
+                  replies.push(new Error("OOM command not allowed"));
+                  errorIndexes.push(i);
+                } else {
+                  replies.push(i);
+                }
+              });
+              throw makeMultiError(replies, errorIndexes);
+            };
             return chain;
           };
         }
@@ -344,7 +352,7 @@ describe("applySnapshot", () => {
     };
     await expect(
       applySnapshot({
-        redis: wrapped as unknown as Redis,
+        redis: wrapped as unknown as RedisClientType,
         threadKey: "messages",
         threadId: "t-fail",
         snapshot: snap,
@@ -354,14 +362,14 @@ describe("applySnapshot", () => {
     expect(await redis.exists(getThreadMetaKey("messages", "t-fail"))).toBe(0);
   });
 
-  it("issues a single pipeline.exec() rather than per-key writes", async () => {
-    let pipelineCalls = 0;
+  it("issues a single multi().execAsPipeline() rather than per-key writes", async () => {
+    let multiCalls = 0;
     const wrapped = new Proxy(redis, {
       get(target, prop, receiver): unknown {
-        if (prop === "pipeline") {
+        if (prop === "multi") {
           return (): unknown => {
-            pipelineCalls++;
-            return (target as unknown as { pipeline: () => unknown }).pipeline();
+            multiCalls++;
+            return (target as unknown as { multi: () => unknown }).multi();
           };
         }
         return Reflect.get(target, prop, receiver) as unknown;
@@ -377,19 +385,19 @@ describe("applySnapshot", () => {
       dedupIds: Array.from({ length: 10 }, (_, i) => `m${i}`),
     };
     await applySnapshot({
-      redis: wrapped as unknown as Redis,
+      redis: wrapped as unknown as RedisClientType,
       threadKey: "messages",
       threadId: "t-1",
       snapshot: snap,
     });
 
-    expect(pipelineCalls).toBe(1);
+    expect(multiCalls).toBe(1);
   });
 
   it("clears any partial residue from a previous failed restore", async () => {
     const listKey = getThreadListKey("messages", "t-1");
     const stateKey = getThreadStateKey("messages", "t-1");
-    await redis.rpush(listKey, "stale-message");
+    await redis.rPush(listKey, "stale-message");
     await redis.set(stateKey, JSON.stringify({ stale: true }));
     // Note: meta is intentionally absent — simulates a half-written restore.
 

package/src/lib/thread/snapshot.ts

@@ -8,7 +8,7 @@
  * tiered thread manager in `tiered.ts` is the only consumer.
  */
 
-import type Redis from "ioredis";
+import type { RedisClientType } from "redis";
 import type { PersistedThreadState } from "../state/types";
 import type { ThreadSnapshot } from "./cold-store";
 import {
@@ -21,7 +21,7 @@ import {
 
 /** Inputs shared by every snapshot operation. */
 interface SnapshotCommon {
-  redis: Redis;
+  redis: RedisClientType;
   threadKey: string;
   threadId: string;
 }
@@ -53,7 +53,7 @@ export async function encodeSnapshot(
   }
   const listKey = getThreadListKey(threadKey, threadId);
   const stateKey = getThreadStateKey(threadKey, threadId);
-  const messages = await redis.lrange(listKey, 0, -1);
+  const messages = await redis.lRange(listKey, 0, -1);
   const stateRaw = await redis.get(stateKey);
   const state =
     stateRaw == null ? null : (JSON.parse(stateRaw) as PersistedThreadState);
@@ -99,43 +99,65 @@ export async function applySnapshot(
   // CROSSSLOT, …) short-circuits before any writes hit the wire —
   // pipelines are non-atomic, so a queued DEL wouldn't stop later
   // commands from accumulating data behind a missing meta marker.
-  await redis.del(listKey, stateKey);
+  await redis.del([listKey, stateKey]);
 
-  // Pipeline the data writes (list/state/dedup) in one round-trip.
-  // Meta is written separately, only after every queued command
-  // succeeded, preserving the "meta-last" crash-safety invariant —
-  // a partial restore must leave meta absent so the next hydrate
-  // retries cleanly.
-  const pipeline = redis.pipeline();
+  // Pipeline the data writes (list/state/dedup) in one round-trip via a
+  // non-transactional `MULTI` (`execAsPipeline`). Meta is written
+  // separately, only after every queued command succeeded, preserving
+  // the "meta-last" crash-safety invariant — a partial restore must
+  // leave meta absent so the next hydrate retries cleanly.
+  const pipeline = redis.multi();
   if (snapshot.messages.length > 0) {
-    pipeline.rpush(listKey, ...snapshot.messages);
+    pipeline.rPush(listKey, snapshot.messages);
     pipeline.expire(listKey, ttlSeconds);
   }
   if (snapshot.state != null) {
-    pipeline.set(stateKey, JSON.stringify(snapshot.state), "EX", ttlSeconds);
+    pipeline.set(stateKey, JSON.stringify(snapshot.state), { EX: ttlSeconds });
   }
   for (const id of snapshot.dedupIds) {
-    pipeline.set(getThreadDedupKey(threadId, id), "1", "EX", ttlSeconds);
+    pipeline.set(getThreadDedupKey(threadId, id), "1", { EX: ttlSeconds });
   }
-  const results = await pipeline.exec();
-  if (results) {
-    const firstErr = results.find(([err]) => err)?.[0] ?? null;
-    if (firstErr) {
-      // Compensate: pipelines are non-atomic, so writes queued after
-      // a failing command (notably dedup SETs) may have landed. Best-
-      // effort clear every key we touched so a leftover dedup marker
-      // can't silently skip a future append with the same id.
-      await redis
-        .del(
-          listKey,
-          stateKey,
-          ...snapshot.dedupIds.map((id) => getThreadDedupKey(threadId, id))
-        )
-        .catch(() => undefined);
-      throw firstErr;
-    }
+  try {
+    await pipeline.execAsPipeline();
+  } catch (err) {
+    // Compensate: pipelines are non-atomic, so writes queued after a
+    // failing command (notably dedup SETs) may have landed. Best-effort
+    // clear every key we touched so a leftover dedup marker can't
+    // silently skip a future append with the same id. node-redis
+    // surfaces per-command failures by rejecting `execAsPipeline` with a
+    // `MultiErrorReply`; we unwrap it to rethrow the first real error.
+    await redis
+      .del([
+        listKey,
+        stateKey,
+        ...snapshot.dedupIds.map((id) => getThreadDedupKey(threadId, id)),
+      ])
+      .catch(() => undefined);
+    throw firstPipelineError(err);
   }
-  await redis.set(metaKey, "1", "EX", ttlSeconds);
+  await redis.set(metaKey, "1", { EX: ttlSeconds });
+}
+
+/**
+ * Unwrap node-redis's `MultiErrorReply` (thrown by `execAsPipeline` when
+ * one or more queued commands fail) to the first underlying error so
+ * callers see the actual Redis error (OOM, WRONGTYPE, …) rather than the
+ * generic aggregate wrapper. The structural check avoids a hard runtime
+ * dependency on the `redis` error class.
+ */
+function firstPipelineError(err: unknown): unknown {
+  if (
+    err != null &&
+    typeof err === "object" &&
+    "replies" in err &&
+    Array.isArray((err as { replies: unknown }).replies)
+  ) {
+    const firstErr = (err as { replies: unknown[] }).replies.find(
+      (r): r is Error => r instanceof Error
+    );
+    if (firstErr) return firstErr;
+  }
+  return err;
 }
 
 /** Configuration for {@link clearHotTier}. */
@@ -159,5 +181,5 @@ export async function clearHotTier(
     getThreadStateKey(threadKey, threadId),
     ...dedupIds.map((id) => getThreadDedupKey(threadId, id)),
   ];
-  await redis.del(...keys);
+  await redis.del(keys);
 }