@decohere/core 0.0.1-dev.125 → 0.0.1-dev.5

package/tests/caching/cache-test-class.ts

@@ -0,0 +1,91 @@
+import { vi } from "vitest";
+import { cache } from "../../src/caching/cache.decorator.js";
+
+// Simple cache implementation for testing
+class MockCache {
+	public get isMemoize(): boolean {
+		return false;
+	}
+	private data = new Map<string, unknown>();
+
+	public get(key: string): unknown {
+		return this.data.get(key);
+	}
+
+	public set(key: string, value: unknown): void {
+		this.data.set(key, value);
+	}
+
+	public has(key: string): boolean {
+		return this.data.has(key);
+	}
+
+	public del(key: string): void {
+		this.data.delete(key);
+	}
+
+	public flushAll(): void {
+		this.data.clear();
+	}
+}
+
+export const CACHE = new MockCache();
+
+export class CacheTestClass {
+	public callCount = 0;
+	public counter = vi.fn();
+
+	@cache({ cache: CACHE })
+	public syncMethod(value: number): number {
+		this.callCount++;
+		this.counter();
+		return value * 2;
+	}
+
+	@cache({ cache: CACHE })
+	public async asyncMethod(value: number): Promise<number> {
+		this.callCount++;
+		this.counter();
+		return value * 3;
+	}
+
+	@cache({ cache: CACHE })
+	public multiArgMethod(arg1: number, arg2: number): number {
+		this.callCount++;
+		this.counter();
+		return arg1 + arg2;
+	}
+
+	@cache({ cache: CACHE })
+	public undefinedMethod(): undefined {
+		this.callCount++;
+		this.counter();
+		return undefined;
+	}
+
+	@cache({ cache: CACHE })
+	public falsyMethod(): number {
+		this.callCount++;
+		this.counter();
+		return 0;
+	}
+
+	@cache({ name: "TEST_CACHE" })
+	public namedCacheMethod(value: number): number {
+		this.callCount++;
+		this.counter();
+		return value * 5;
+	}
+
+	@cache()
+	public defaultOptionsMethod(value: string): string {
+		this.callCount++;
+		this.counter();
+		return `test-${value}`;
+	}
+
+	public reset(): void {
+		this.callCount = 0;
+		this.counter.mockReset();
+	}
+}

package/tests/caching/cache.decorator.spec.ts

@@ -0,0 +1,259 @@
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Caching } from "../../src/caching/cache-manager.js";
+import { pathToFileUrl } from "../../src/io/url-to-path.js";
+import { CACHE } from "./cache-test-class.js";
+
+// Test class import path constant
+const CACHE_TEST_CLASS_PATH = "./cache-test-class.js";
+
+// Function-based import URL for easier refactoring
+const importUrl = () => getImportUrl(CACHE_TEST_CLASS_PATH);
+
+// Set up the test cache in Caching manager
+Caching.setCache("TEST_CACHE", CACHE);
+
+// Helper function to create a versioned import URL for cache busting
+function getImportUrl(filename: string): string {
+	const modulePath = path.resolve(__dirname, filename);
+	const moduleUrl = pathToFileUrl(modulePath);
+	return `${moduleUrl}?version=${Date.now()}`;
+}
+
+describe("cache decorator", () => {
+	beforeEach(() => {
+		vi.resetAllMocks();
+	});
+
+	afterEach(() => {
+		Caching.flushAllCaches();
+		CACHE.flushAll();
+		delete process.env.FORGE_DISABLE_CACHE;
+	});
+
+	describe("FORGE_DISABLE_CACHE environment variable behavior", () => {
+		it("should cache normally by default", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.syncMethod(5);
+			const result2 = instance.syncMethod(5);
+
+			expect(result1).toBe(10);
+			expect(result2).toBe(10);
+			expect(instance.callCount).toBe(1); // Should be cached
+		});
+
+		it("should disable caching when FORGE_DISABLE_CACHE=true", async () => {
+			process.env.FORGE_DISABLE_CACHE = "true";
+
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.syncMethod(5);
+			const result2 = instance.syncMethod(5);
+
+			expect(result1).toBe(10);
+			expect(result2).toBe(10);
+			expect(instance.callCount).toBe(2); // Should NOT be cached
+		});
+
+		it("should disable caching for async methods when FORGE_DISABLE_CACHE=true", async () => {
+			process.env.FORGE_DISABLE_CACHE = "true";
+
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = await instance.asyncMethod(5);
+			const result2 = await instance.asyncMethod(5);
+
+			expect(result1).toBe(15);
+			expect(result2).toBe(15);
+			expect(instance.callCount).toBe(2); // Should NOT be cached
+		});
+
+		it("should not interact with cache when disabled", async () => {
+			process.env.FORGE_DISABLE_CACHE = "true";
+
+			const setSpy = vi.spyOn(CACHE, "set");
+			const getSpy = vi.spyOn(CACHE, "get");
+			const hasSpy = vi.spyOn(CACHE, "has");
+
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			instance.defaultOptionsMethod("value");
+			instance.defaultOptionsMethod("value");
+
+			expect(setSpy).not.toHaveBeenCalled();
+			expect(getSpy).not.toHaveBeenCalled();
+			expect(hasSpy).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("synchronous methods", () => {
+		it("should cache sync method results", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.syncMethod(5);
+			const result2 = instance.syncMethod(5);
+
+			expect(result1).toBe(10);
+			expect(result2).toBe(10);
+			expect(instance.callCount).toBe(1);
+			expect(instance.counter).toHaveBeenCalledTimes(1);
+		});
+
+		it("should cache different arguments separately", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.syncMethod(5);
+			const result2 = instance.syncMethod(10);
+			const result3 = instance.syncMethod(5);
+
+			expect(result1).toBe(10);
+			expect(result2).toBe(20);
+			expect(result3).toBe(10);
+			expect(instance.callCount).toBe(2); // Called for 5 and 10, but cached for second 5
+		});
+
+		it("should cache multiple arguments", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.multiArgMethod(3, 4);
+			const result2 = instance.multiArgMethod(3, 4);
+			const result3 = instance.multiArgMethod(5, 6);
+
+			expect(result1).toBe(7);
+			expect(result2).toBe(7);
+			expect(result3).toBe(11);
+			expect(instance.callCount).toBe(2); // Called for (3,4) and (5,6)
+		});
+
+		it("should cache undefined return values", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.undefinedMethod();
+			const result2 = instance.undefinedMethod();
+
+			expect(result1).toBeUndefined();
+			expect(result2).toBeUndefined();
+			expect(instance.callCount).toBe(1); // Should be cached
+		});
+
+		it("should cache falsy return values", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.falsyMethod();
+			const result2 = instance.falsyMethod();
+
+			expect(result1).toBe(0);
+			expect(result2).toBe(0);
+			expect(instance.callCount).toBe(1); // Should be cached
+		});
+	});
+
+	describe("asynchronous methods", () => {
+		it("should cache async method results", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = await instance.asyncMethod(5);
+			const result2 = await instance.asyncMethod(5);
+
+			expect(result1).toBe(15);
+			expect(result2).toBe(15);
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should return Promise for async methods", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result = instance.asyncMethod(5);
+
+			expect(result).toBeInstanceOf(Promise);
+			await result; // Wait for completion
+		});
+
+		it("should cache different async arguments separately", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = await instance.asyncMethod(5);
+			const result2 = await instance.asyncMethod(10);
+			const result3 = await instance.asyncMethod(5);
+
+			expect(result1).toBe(15);
+			expect(result2).toBe(30);
+			expect(result3).toBe(15);
+			expect(instance.callCount).toBe(2);
+		});
+	});
+
+	describe("cache isolation and sharing", () => {
+		it("should isolate cache per instance", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance1 = new CacheTestClass();
+			const instance2 = new CacheTestClass();
+
+			const result1 = instance1.syncMethod(5);
+			const result2 = instance2.syncMethod(5);
+
+			expect(result1).toBe(10);
+			expect(result2).toBe(10);
+			// Each instance has its own cache entry — both execute the method
+			expect(instance1.callCount).toBe(1);
+			expect(instance2.callCount).toBe(1);
+		});
+	});
+
+	describe("named cache support", () => {
+		it("should use named cache from Caching manager", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.namedCacheMethod(5);
+			const result2 = instance.namedCacheMethod(5);
+
+			expect(result1).toBe(25);
+			expect(result2).toBe(25);
+			expect(instance.callCount).toBe(1); // Should be cached
+		});
+
+		it("should clear named cache via Caching manager", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.namedCacheMethod(5);
+			expect(result1).toBe(25);
+			expect(instance.callCount).toBe(1);
+
+			// Clear the cache
+			Caching.flushAllCaches();
+
+			const result2 = instance.namedCacheMethod(5);
+			expect(result2).toBe(25);
+			expect(instance.callCount).toBe(2); // Should be called again after clear
+		});
+	});
+
+	describe("default cache options", () => {
+		it("should work with default options", async () => {
+			const { CacheTestClass } = await import(importUrl());
+			const instance = new CacheTestClass();
+
+			const result1 = instance.defaultOptionsMethod("value");
+			const result2 = instance.defaultOptionsMethod("value");
+
+			expect(result1).toBe("test-value");
+			expect(result2).toBe("test-value");
+			expect(instance.callCount).toBe(1); // Should be cached with default cache
+		});
+	});
+});

package/tests/caching/invalidate-cache-test-class.ts

@@ -0,0 +1,52 @@
+import type { ICache } from "../../src/caching/cache.js";
+import { invalidateCache, memoize } from "../../src/caching/index.js";
+
+class MockCache implements ICache {
+	public get isMemoize(): boolean {
+		return true;
+	}
+
+	private data = new Map<string, unknown>();
+
+	public get(key: string): unknown {
+		return this.data.get(key);
+	}
+
+	public set(key: string, value: unknown): void {
+		this.data.set(key, value);
+	}
+
+	public has(key: string): boolean {
+		return this.data.has(key);
+	}
+
+	public del(key: string): void {
+		this.data.delete(key);
+	}
+
+	public flushAll(): void {
+		this.data.clear();
+	}
+}
+
+export const TEST_CACHE = new MockCache();
+
+export class InvalidateCacheTestClass {
+	public callCount = 0;
+
+	@memoize({ cache: TEST_CACHE })
+	public getValue(): string {
+		this.callCount++;
+		return `value_${this.callCount}`;
+	}
+
+	@invalidateCache("getValue", { cache: TEST_CACHE })
+	public setValue(_value: string): void {
+		// synchronous write — invalidation happens after this returns
+	}
+
+	@invalidateCache("getValue", { cache: TEST_CACHE })
+	public async setValueAsync(_value: string): Promise<void> {
+		// async write — invalidation happens after the promise resolves
+	}
+}

package/tests/caching/invalidate-cache.decorator.spec.ts

@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { ICache } from "../../src/caching/cache.js";
+import { Caching } from "../../src/caching/cache-manager.js";
+import { invalidateCache, invalidateMemoize, memoize } from "../../src/caching/index.js";
+
+class TestCache implements ICache {
+	public get isMemoize() {
+		return true;
+	}
+	private data = new Map<string, unknown>();
+	public get(key: string) {
+		return this.data.get(key);
+	}
+	public set(key: string, value: unknown) {
+		this.data.set(key, value);
+	}
+	public has(key: string) {
+		return this.data.has(key);
+	}
+	public del(key: string) {
+		this.data.delete(key);
+	}
+	public flushAll() {
+		this.data.clear();
+	}
+}
+
+const TEST_CACHE = new TestCache();
+
+// Function reference: apply invalidateCache after class definition so the prototype is available
+class MemoizedClass {
+	public callCount = 0;
+
+	@memoize({ cache: TEST_CACHE })
+	public getValue(): string {
+		this.callCount++;
+		return `value_${this.callCount}`;
+	}
+
+	public invalidate(): void {}
+	public async invalidateAsync(): Promise<void> {}
+}
+
+for (const key of ["invalidate", "invalidateAsync"] as const) {
+	const desc = Object.getOwnPropertyDescriptor(MemoizedClass.prototype, key)!;
+	invalidateMemoize(MemoizedClass.prototype.getValue, { cache: TEST_CACHE })(
+		MemoizedClass.prototype,
+		key,
+		desc,
+	);
+	Object.defineProperty(MemoizedClass.prototype, key, desc);
+}
+
+// String overload: raw cache key eviction (no generateCacheKey semantics)
+class RawKeyClass {
+	@invalidateCache("myRawKey", { cache: TEST_CACHE })
+	public clearEntry(): void {}
+}
+
+describe("invalidateCache decorator", () => {
+	afterEach(() => {
+		TEST_CACHE.flushAll();
+		Caching.flushAllCaches();
+	});
+
+	describe("function reference", () => {
+		it("should evict cache for the referenced method after synchronous invalidator runs", () => {
+			const instance = new MemoizedClass();
+
+			instance.getValue(); // callCount = 1, cached
+			instance.getValue(); // from cache
+			expect(instance.callCount).toBe(1);
+
+			instance.invalidate();
+
+			instance.getValue(); // evicted — re-executes
+			expect(instance.callCount).toBe(2);
+		});
+
+		it("should evict cache for the referenced method after async invalidator resolves", async () => {
+			const instance = new MemoizedClass();
+
+			instance.getValue(); // callCount = 1, cached
+			instance.getValue(); // from cache
+			expect(instance.callCount).toBe(1);
+
+			await instance.invalidateAsync();
+
+			instance.getValue(); // evicted — re-executes
+			expect(instance.callCount).toBe(2);
+		});
+
+		it("should use the custom cache supplied via options", () => {
+			const instance = new MemoizedClass();
+
+			instance.getValue(); // callCount = 1, cached in TEST_CACHE
+			expect(instance.callCount).toBe(1);
+
+			instance.invalidate(); // evicts TEST_CACHE entry
+
+			instance.getValue(); // callCount = 2
+			expect(instance.callCount).toBe(2);
+
+			TEST_CACHE.flushAll();
+			instance.getValue(); // callCount = 3
+			expect(instance.callCount).toBe(3);
+		});
+	});
+
+	describe("string (raw cache key)", () => {
+		it("should delete the exact cache key when passed a string", () => {
+			TEST_CACHE.set("myRawKey", "someValue");
+			expect(TEST_CACHE.has("myRawKey")).toBe(true);
+
+			new RawKeyClass().clearEntry();
+
+			expect(TEST_CACHE.has("myRawKey")).toBe(false);
+		});
+	});
+});

package/tests/caching/memoize-test-class.ts

@@ -0,0 +1,99 @@
+import { vi } from "vitest";
+import { memoize } from "../../src/caching/index.js";
+
+// Simple memoization cache implementation for testing
+class MockMemoizeCache {
+	public get isMemoize(): boolean {
+		return true;
+	}
+	private data = new Map<string, unknown>();
+
+	public get(key: string): unknown {
+		return this.data.get(key);
+	}
+
+	public set(key: string, value: unknown): void {
+		this.data.set(key, value);
+	}
+
+	public has(key: string): boolean {
+		return this.data.has(key);
+	}
+
+	public del(key: string): void {
+		this.data.delete(key);
+	}
+
+	public flushAll(): void {
+		this.data.clear();
+	}
+}
+
+export const MEMOIZE_CACHE = new MockMemoizeCache();
+
+export class MemoizeTestClass {
+	public callCount = 0;
+	public counter = vi.fn();
+
+	public reset(): void {
+		this.callCount = 0;
+		this.counter.mockClear();
+		MEMOIZE_CACHE.flushAll();
+	}
+
+	@memoize({ cache: MEMOIZE_CACHE })
+	public syncMethod(value: number): number {
+		this.callCount++;
+		this.counter();
+		return value * 2;
+	}
+
+	@memoize({ cache: MEMOIZE_CACHE })
+	public async asyncMethod(value: number): Promise<number> {
+		this.callCount++;
+		this.counter();
+		return value * 3;
+	}
+
+	@memoize({ cache: MEMOIZE_CACHE })
+	public multiArgMethod(arg1: number, arg2: number): number {
+		this.callCount++;
+		this.counter();
+		return arg1 + arg2;
+	}
+
+	@memoize({ cache: MEMOIZE_CACHE })
+	public undefinedMethod(): undefined {
+		this.callCount++;
+		this.counter();
+		return undefined;
+	}
+
+	@memoize({ cache: MEMOIZE_CACHE })
+	public falsyMethod(): number {
+		this.callCount++;
+		this.counter();
+		return 0;
+	}
+
+	@memoize({ cache: MEMOIZE_CACHE, name: "custom-cache" })
+	public namedCacheMethod(value: number): number {
+		this.callCount++;
+		this.counter();
+		return value * 4;
+	}
+
+	@memoize()
+	public defaultCacheMethod(value: number): number {
+		this.callCount++;
+		this.counter();
+		return value * 5;
+	}
+
+	@memoize()
+	public objectMethod(id: number): { id: number; value: number } {
+		this.callCount++;
+		this.counter();
+		return { id, value: id * 10 };
+	}
+}