Merge branch 'main' into dqbd/util-typed-node

Author: dqbd

.gitignore

@@ -22,3 +22,4 @@ dist-cjs
 tmp/
 __pycache__
 .DS_Store
+tsconfig.vitest-temp.json

libs/checkpoint/jest.config.cjs

@@ -21,10 +21,10 @@
     "lint": "yarn lint:eslint && yarn lint:dpdm",
     "lint:fix": "yarn lint:eslint --fix && yarn lint:dpdm",
     "prepack": "yarn build",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=\\.int\\.test.ts --testTimeout 30000 --maxWorkers=50%",
-    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch --testPathIgnorePatterns=\\.int\\.test.ts",
-    "test:single": "NODE_OPTIONS=--experimental-vm-modules yarn run jest --config jest.config.cjs --testTimeout 100000",
-    "test:int": "NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern=\\.int\\.test.ts --testTimeout 100000 --maxWorkers=50%",
+    "test": "vitest",
+    "test:watch": "vitest watch",
+    "test:single": "vitest run",
+    "test:int": "vitest run --mode int",
     "format": "prettier --config .prettierrc --write \"src\"",
     "format:check": "prettier --config .prettierrc --check \"src\""
   },
@@ -61,7 +61,8 @@
     "rollup": "^4.37.0",
     "ts-jest": "^29.1.0",
     "tsx": "^4.19.3",
-    "typescript": "^4.9.5 || ^5.4.5"
+    "typescript": "^4.9.5 || ^5.4.5",
+    "vitest": "^3.1.2"
   },
   "publishConfig": {
     "access": "public",

libs/checkpoint/jest.env.cjs

@@ -0,0 +1,44 @@
+import { SerializerProtocol } from "../serde/base.js";
+import { JsonPlusSerializer } from "../serde/jsonplus.js";
+
+export type CacheNamespace = string[];
+export type CacheFullKey = [namespace: CacheNamespace, key: string];
+
+export abstract class BaseCache<V = unknown> {
+  serde: SerializerProtocol = new JsonPlusSerializer();
+
+  /**
+   * Initialize the cache with a serializer.
+   *
+   * @param serde - The serializer to use.
+   */
+  constructor(serde?: SerializerProtocol) {
+    this.serde = serde || this.serde;
+  }
+
+  /**
+   * Get the cached values for the given keys.
+   *
+   * @param keys - The keys to get.
+   */
+  abstract get(
+    keys: CacheFullKey[]
+  ): Promise<{ key: CacheFullKey; value: V }[]>;
+
+  /**
+   * Set the cached values for the given keys and TTLs.
+   *
+   * @param pairs - The pairs to set.
+   */
+  abstract set(
+    pairs: { key: CacheFullKey; value: V; ttl?: number }[]
+  ): Promise<void>;
+
+  /**
+   * Delete the cached values for the given namespaces.
+   * If no namespaces are provided, clear all cached values.
+   *
+   * @param namespaces - The namespaces to clear.
+   */
+  abstract clear(namespaces: CacheNamespace[]): Promise<void>;
+}

libs/checkpoint/package.json

@@ -0,0 +1,2 @@
+export * from "./base.js";
+export * from "./memory.js";

libs/checkpoint/src/cache/base.ts

@@ -0,0 +1,70 @@
+import { BaseCache, type CacheFullKey, type CacheNamespace } from "./base.js";
+
+export class InMemoryCache<V = unknown> extends BaseCache<V> {
+  private cache: {
+    [namespace: string]: {
+      [key: string]: {
+        enc: string;
+        val: Uint8Array | string;
+        exp: number | null;
+      };
+    };
+  } = {};
+
+  async get(keys: CacheFullKey[]): Promise<{ key: CacheFullKey; value: V }[]> {
+    if (!keys.length) return [];
+    const now = Date.now();
+    return (
+      await Promise.all(
+        keys.map(
+          async (fullKey): Promise<{ key: CacheFullKey; value: V }[]> => {
+            const [namespace, key] = fullKey;
+            const strNamespace = namespace.join(",");
+
+            if (strNamespace in this.cache && key in this.cache[strNamespace]) {
+              const cached = this.cache[strNamespace][key];
+              if (cached.exp == null || now < cached.exp) {
+                const value = await this.serde.loadsTyped(
+                  cached.enc,
+                  cached.val
+                );
+                return [{ key: fullKey, value }];
+              } else {
+                delete this.cache[strNamespace][key];
+              }
+            }
+
+            return [];
+          }
+        )
+      )
+    ).flat();
+  }
+
+  async set(
+    pairs: { key: CacheFullKey; value: V; ttl?: number }[]
+  ): Promise<void> {
+    const now = Date.now();
+    for (const { key: fullKey, value, ttl } of pairs) {
+      const [namespace, key] = fullKey;
+      const strNamespace = namespace.join(",");
+      const [enc, val] = await this.serde.dumpsTyped(value);
+      const exp = ttl != null ? ttl * 1000 + now : null;
+
+      this.cache[strNamespace] ??= {};
+      this.cache[strNamespace][key] = { enc, val, exp };
+    }
+  }
+
+  async clear(namespaces: CacheNamespace[]): Promise<void> {
+    if (!namespaces.length) {
+      this.cache = {};
+      return;
+    }
+
+    for (const namespace of namespaces) {
+      const strNamespace = namespace.join(",");
+      if (strNamespace in this.cache) delete this.cache[strNamespace];
+    }
+  }
+}

libs/checkpoint/src/cache/index.ts

@@ -5,3 +5,4 @@ export * from "./types.js";
 export * from "./serde/base.js";
 export * from "./serde/types.js";
 export * from "./store/index.js";
+export * from "./cache/index.js";

libs/checkpoint/src/cache/memory.ts

@@ -1,4 +1,4 @@
-import { it, expect } from "@jest/globals";
+import { it, expect } from "vitest";
 import { AIMessage, HumanMessage } from "@langchain/core/messages";
 import { uuid6 } from "../../id.js";
 import { JsonPlusSerializer } from "../jsonplus.js";

libs/checkpoint/src/index.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { InMemoryCache } from "../cache/memory.js";
+
+describe("InMemoryCache", () => {
+  let cache: InMemoryCache<string>;
+
+  beforeEach(() => {
+    cache = new InMemoryCache<string>();
+  });
+
+  describe("get and set", () => {
+    it("should set and get a single value", async () => {
+      const key: [string[], string] = [["test"], "key1"];
+      await cache.set([{ key, value: "value1", ttl: 1000 }]);
+      expect(await cache.get([key])).toEqual([{ key, value: "value1" }]);
+    });
+
+    it("should handle multiple values", async () => {
+      const pairs = [
+        {
+          key: [["test"], "key1"] as [string[], string],
+          value: "value1",
+          ttl: 1000,
+        },
+        {
+          key: [["test"], "key2"] as [string[], string],
+          value: "value2",
+          ttl: 1000,
+        },
+      ];
+
+      await cache.set(pairs);
+      const result = await cache.get(pairs.map((p) => p.key));
+
+      expect(result).toEqual([
+        { key: [["test"], "key1"], value: "value1" },
+        { key: [["test"], "key2"], value: "value2" },
+      ]);
+    });
+
+    it("should return empty array for non-existent keys", async () => {
+      const result = await cache.get([[["test"], "nonexistent"]]);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("TTL behavior", () => {
+    it("should expire values after TTL", async () => {
+      const key: [string[], string] = [["test"], "key1"];
+      await cache.set([{ key, value: "value1", ttl: 0.1 }]); // 100ms TTL
+
+      // Wait for TTL to expire
+      await new Promise((resolve) => {
+        setTimeout(resolve, 150);
+      });
+
+      expect(await cache.get([key])).toEqual([]);
+    });
+
+    it("should not expire values before TTL", async () => {
+      const key: [string[], string] = [["test"], "key1"];
+      await cache.set([{ key, value: "value1", ttl: 0.2 }]); // 200ms TTL
+
+      // Check before TTL expires
+      await new Promise((resolve) => {
+        setTimeout(resolve, 100);
+      });
+
+      const result = await cache.get([key]);
+      expect(result).toHaveLength(1);
+      expect(result[0].value).toBe("value1");
+    });
+  });
+
+  describe("namespace handling", () => {
+    it("should handle different namespaces separately", async () => {
+      const pairs = [
+        {
+          key: [["ns1"], "key1"] as [string[], string],
+          value: "value1",
+          ttl: 1000,
+        },
+        {
+          key: [["ns2"], "key1"] as [string[], string],
+          value: "value2",
+          ttl: 1000,
+        },
+      ];
+
+      await cache.set(pairs);
+      const result = await cache.get(pairs.map((p) => p.key));
+
+      expect(result).toEqual([
+        { key: [["ns1"], "key1"], value: "value1" },
+        { key: [["ns2"], "key1"], value: "value2" },
+      ]);
+    });
+
+    it("should handle nested namespaces", async () => {
+      const key: [string[], string] = [["ns1", "subns"], "key1"];
+      await cache.set([{ key, value: "value1", ttl: 1.0 }]);
+
+      expect(await cache.get([key])).toEqual([{ key, value: "value1" }]);
+    });
+  });
+
+  describe("clear operations", () => {
+    it("should clear specific namespace", async () => {
+      const pairs = [
+        {
+          key: [["ns1"], "key1"] as [string[], string],
+          value: "value1",
+          ttl: 1.0,
+        },
+        {
+          key: [["ns2"], "key1"] as [string[], string],
+          value: "value2",
+          ttl: 1.0,
+        },
+      ];
+
+      await cache.set(pairs);
+      await cache.clear([["ns1"]]);
+
+      expect(await cache.get(pairs.map((p) => p.key))).toEqual([
+        { key: [["ns2"], "key1"], value: "value2" },
+      ]);
+    });
+
+    it("should clear all namespaces when no namespace specified", async () => {
+      const pairs = [
+        {
+          key: [["ns1"], "key1"] as [string[], string],
+          value: "value1",
+          ttl: 1.0,
+        },
+        {
+          key: [["ns2"], "key1"] as [string[], string],
+          value: "value2",
+          ttl: 1.0,
+        },
+      ];
+
+      await cache.set(pairs);
+      await cache.clear([]);
+
+      expect(await cache.get(pairs.map((p) => p.key))).toEqual([]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle empty key arrays", async () => {
+      expect(await cache.get([])).toEqual([]);
+    });
+
+    it("should handle empty namespace arrays", async () => {
+      expect(await cache.clear([])).toBeUndefined();
+    });
+
+    it("should handle setting empty pairs", async () => {
+      expect(await cache.set([])).toBeUndefined();
+    });
+  });
+});

libs/checkpoint/src/serde/tests/jsonplus.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "@jest/globals";
+import { describe, it, expect } from "vitest";
 import {
   Checkpoint,
   CheckpointTuple,

libs/checkpoint/src/tests/cache.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from "@jest/globals";
+import { describe, it, expect, beforeEach } from "vitest";
 import { InMemoryStore } from "../store/memory.js";
 import { InvalidNamespaceError } from "../store/base.js";