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

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

@@ -0,0 +1,203 @@
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { pathToFileUrl } from "../../src/io/url-to-path.js";
+import { MEMOIZE_CACHE } from "./memoize-test-class.js";
+
+// Test class import path constant
+const MEMOIZE_TEST_CLASS_PATH = "./memoize-test-class.js";
+
+// Function-based import URL for easier refactoring
+const importUrl = () => getImportUrl(MEMOIZE_TEST_CLASS_PATH);
+
+// 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("memoize decorator", () => {
+	beforeEach(() => {
+		vi.resetAllMocks();
+	});
+
+	afterEach(() => {
+		MEMOIZE_CACHE.flushAll();
+		delete process.env.FORGE_DISABLE_CACHE;
+	});
+
+	describe("FORGE_DISABLE_CACHE environment variable behavior", () => {
+		it("should memoize normally by default", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			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 memoized
+		});
+
+		it("should not memoize when FORGE_DISABLE_CACHE=true", async () => {
+			process.env.FORGE_DISABLE_CACHE = "true";
+
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			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 memoized
+		});
+	});
+
+	describe("memoization functionality", () => {
+		it("should memoize synchronous method results", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = instance.syncMethod(42);
+			const result2 = instance.syncMethod(42);
+
+			expect(result1).toBe(84);
+			expect(result2).toBe(84);
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should memoize asynchronous method results", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = await instance.asyncMethod(10);
+			const result2 = await instance.asyncMethod(10);
+
+			expect(result1).toBe(30);
+			expect(result2).toBe(30);
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should handle multiple arguments", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = instance.multiArgMethod(5, 3);
+			const result2 = instance.multiArgMethod(5, 3);
+			const result3 = instance.multiArgMethod(5, 4);
+
+			expect(result1).toBe(8);
+			expect(result2).toBe(8);
+			expect(result3).toBe(9);
+			expect(instance.callCount).toBe(2); // Two different argument sets
+		});
+
+		it("should handle undefined return values", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = instance.undefinedMethod();
+			const result2 = instance.undefinedMethod();
+
+			expect(result1).toBeUndefined();
+			expect(result2).toBeUndefined();
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should handle falsy return values", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = instance.falsyMethod();
+			const result2 = instance.falsyMethod();
+
+			expect(result1).toBe(0);
+			expect(result2).toBe(0);
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should support custom cache keys", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = instance.namedCacheMethod(7);
+			const result2 = instance.namedCacheMethod(7);
+
+			expect(result1).toBe(28);
+			expect(result2).toBe(28);
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should work with default cache", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const result1 = instance.defaultCacheMethod(6);
+			const result2 = instance.defaultCacheMethod(6);
+
+			expect(result1).toBe(30);
+			expect(result2).toBe(30);
+			expect(instance.callCount).toBe(1);
+		});
+	});
+
+	describe("object reference behavior", () => {
+		it("should call method only once for same arguments", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			instance.objectMethod(5);
+			instance.objectMethod(5);
+
+			expect(instance.callCount).toBe(1);
+		});
+
+		it("should return same object reference (not a clone)", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const obj1 = instance.objectMethod(5);
+			const obj2 = instance.objectMethod(5);
+
+			expect(obj1).toBe(obj2);
+		});
+
+		it("should preserve mutations across all references", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const obj1 = instance.objectMethod(5);
+			obj1.value = 999;
+
+			const obj2 = instance.objectMethod(5);
+
+			expect(obj2.value).toBe(999);
+		});
+
+		it("should maintain same reference after mutation", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			const obj1 = instance.objectMethod(5);
+			obj1.value = 999;
+
+			const obj2 = instance.objectMethod(5);
+
+			expect(obj2).toBe(obj1);
+		});
+
+		it("should not call method again after retrieving mutated object", async () => {
+			const { MemoizeTestClass } = await import(importUrl());
+			const instance = new MemoizeTestClass();
+
+			instance.objectMethod(5);
+			const callCountAfterFirst = instance.callCount;
+
+			instance.objectMethod(5);
+			const callCountAfterSecond = instance.callCount;
+
+			expect(callCountAfterSecond).toBe(callCountAfterFirst);
+		});
+	});
+});

package/tests/cli/command.model.spec.ts

@@ -0,0 +1,91 @@
+import type { OptionValues } from "commander";
+import { expect, it, vi } from "vitest";
+import type { Action } from "../../src/cli/index.js";
+import { ActionResponse, DecohereCommand } from "../../src/cli/index.js";
+
+type TestActions = {
+	a: Action;
+	b: Action;
+};
+
+class AAction implements Action {
+	public constructor(
+		private readonly response: ActionResponse = ActionResponse.Success("a"),
+	) {}
+
+	public async run(): Promise<ActionResponse> {
+		return this.response;
+	}
+}
+
+class BAction implements Action {
+	public constructor(
+		private readonly response: ActionResponse = ActionResponse.Success("b"),
+	) {}
+
+	public async run(): Promise<ActionResponse> {
+		return this.response;
+	}
+}
+
+class TestCommand extends DecohereCommand<TestActions> {
+	public override get actions() {
+		return [AAction, BAction] as const;
+	}
+
+	public constructor() {
+		super("test");
+	}
+}
+
+it("does not throw when an action is skipped", async () => {
+	const command = new TestCommand();
+	const actions: TestActions = {
+		a: new AAction(ActionResponse.Skipped("a")),
+		b: new BAction(ActionResponse.Success("b")),
+	};
+	const runA = vi.spyOn(actions.a, "run");
+	const runB = vi.spyOn(actions.b, "run");
+
+	const response = await command.run(actions, {} as OptionValues);
+	expect(runA).toHaveBeenCalledTimes(1);
+	expect(runB).toHaveBeenCalledTimes(1);
+	expect(response.a?.skipped).toBe(true);
+	expect(response.b?.succeeded).toBe(true);
+});
+
+it("throws when an action returns a non-skipped error", async () => {
+	const command = new TestCommand();
+	const actions: TestActions = {
+		a: new AAction(ActionResponse.Error("a", "a failed")),
+		b: new BAction(ActionResponse.Skipped("b")),
+	};
+
+	await expect(command.run(actions, {} as OptionValues)).rejects.toThrow(
+		"test command failed",
+	);
+});
+
+it("throws when mapped action constructor is missing", async () => {
+	class MissingBCommand extends DecohereCommand<TestActions> {
+		public override get actions() {
+			return [AAction, BAction] as const;
+		}
+
+		public constructor() {
+			super("test");
+		}
+	}
+
+	const command = new MissingBCommand();
+	const actions: TestActions = {
+		a: new AAction(),
+		b: {
+			run: async () => ActionResponse.Success("b"),
+		},
+	};
+
+	await expect(command.run(actions, {} as OptionValues)).rejects.toThrow(
+		"missing action instance for BAction",
+	);
+});

package/tests/collections/merge-arrays.spec.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { collections } from "../../src/collections/index.js";
+
+describe("merge-arrays functions", () => {
+	describe("mergeBy", () => {
+		it("should merge arrays and prefer second array values for duplicate keys", () => {
+			const first = [
+				{ id: "build", value: "default-build" },
+				{ id: "lint", value: "default-lint" },
+			];
+			const second = [
+				{ id: "build", value: "custom-build" },
+				{ id: "test", value: "custom-test" },
+			];
+
+			const result = collections.mergeBy(first, second, (item) => item.id);
+
+			expect(result).toEqual([
+				{ id: "build", value: "custom-build" },
+				{ id: "lint", value: "default-lint" },
+				{ id: "test", value: "custom-test" },
+			]);
+		});
+
+		it("should return an empty array when both arrays are empty", () => {
+			expect(collections.mergeBy([], [], () => "")).toEqual([]);
+		});
+	});
+
+	describe("mergeByKey", () => {
+		it("should merge arrays by key and prefer second array values", () => {
+			const first = [
+				{ name: "build", order: 1 },
+				{ name: "lint", order: 2 },
+			];
+			const second = [
+				{ name: "build", order: 100 },
+				{ name: "test", order: 3 },
+			];
+
+			const result = collections.mergeByKey(first, second, "name");
+
+			expect(result).toEqual([
+				{ name: "build", order: 100 },
+				{ name: "lint", order: 2 },
+				{ name: "test", order: 3 },
+			]);
+		});
+	});
+});

package/tests/collections/sum.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { collections } from "../../src/collections/index.js";
+
+describe("sum functions", () => {
+	describe("sumByKey", () => {
+		it("should sum numeric values from object array using key selector", () => {
+			const items = [{ value: 10 }, { value: 20 }, { value: 30 }];
+			const result = collections.sumByKey(items, "value");
+			expect(result).toBe(60);
+		});
+
+		it("should handle empty array", () => {
+			const items: { value: number }[] = [];
+			const result = collections.sumByKey(items, "value");
+			expect(result).toBe(0);
+		});
+
+		it("should handle null/undefined items", () => {
+			const items: Array<{ value: number } | null | undefined> = [
+				{ value: 10 },
+				null,
+				{ value: 20 },
+			];
+			const result = collections.sumByKey(items, "value");
+			expect(result).toBe(30);
+		});
+
+		it("should treat non-numeric values as 0", () => {
+			const items: Array<{ value: number | string }> = [
+				{ value: 10 },
+				{ value: "string" },
+				{ value: 20 },
+			];
+			const result = collections.sumByKey(items, "value");
+			expect(result).toBe(30);
+		});
+
+		it("should work with different property names", () => {
+			const items = [{ price: 5.5 }, { price: 10.25 }, { price: 3.75 }];
+			const result = collections.sumByKey(items, "price");
+			expect(result).toBe(19.5);
+		});
+	});
+
+	describe("sumBy", () => {
+		it("should sum using custom selector function", () => {
+			const items = [
+				{ value: 10, multiplier: 2 },
+				{ value: 20, multiplier: 3 },
+				{ value: 30, multiplier: 1 },
+			];
+			const result = collections.sumBy(items, (item) => item.value * item.multiplier);
+			expect(result).toBe(110); // 10*2 + 20*3 + 30*1
+		});
+
+		it("should handle empty array with function selector", () => {
+			const items: { value: number }[] = [];
+			const result = collections.sumBy(items, (item) => item.value);
+			expect(result).toBe(0);
+		});
+
+		it("should work with complex calculations", () => {
+			const items = [
+				{ quantity: 5, price: 10 },
+				{ quantity: 3, price: 20 },
+				{ quantity: 2, price: 15 },
+			];
+			const result = collections.sumBy(items, (item) => item.quantity * item.price);
+			expect(result).toBe(140); // 5*10 + 3*20 + 2*15
+		});
+
+		it("should handle negative values", () => {
+			const items = [{ value: 10 }, { value: -5 }, { value: 20 }];
+			const result = collections.sumBy(items, (item) => item.value);
+			expect(result).toBe(25);
+		});
+
+		it("should treat non-numeric function results as 0", () => {
+			const items = [{ value: 10 }, { value: 20 }, { value: 30 }];
+			const result = collections.sumBy(items, (item) =>
+				item.value > 15 ? item.value : ("invalid" as unknown as number),
+			);
+			expect(result).toBe(50); // Only 20 and 30 are summed
+		});
+	});
+});

package/tests/collections/unique-objects.spec.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from "vitest";
+import { collections } from "../../src/collections/index.js";
+
+describe("unique-objects functions", () => {
+	describe("uniqueObjectsByKey", () => {
+		it("should remove duplicate objects based on key property", () => {
+			const items = [
+				{ id: 1, name: "Alice" },
+				{ id: 2, name: "Bob" },
+				{ id: 1, name: "Alice Duplicate" },
+			];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(2);
+			expect(result[0]).toEqual({ id: 1, name: "Alice Duplicate" });
+			expect(result[1]).toEqual({ id: 2, name: "Bob" });
+		});
+
+		it("should keep last occurrence when duplicates exist", () => {
+			const items = [
+				{ id: 1, value: "first" },
+				{ id: 1, value: "second" },
+				{ id: 1, value: "third" },
+			];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(1);
+			expect(result[0].value).toBe("third");
+		});
+
+		it("should handle empty array", () => {
+			const items: { id: number }[] = [];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toEqual([]);
+		});
+
+		it("should handle array with single item", () => {
+			const items = [{ id: 1, name: "Alice" }];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(1);
+			expect(result[0]).toEqual({ id: 1, name: "Alice" });
+		});
+
+		it("should handle all unique items", () => {
+			const items = [
+				{ id: 1, name: "Alice" },
+				{ id: 2, name: "Bob" },
+				{ id: 3, name: "Charlie" },
+			];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(3);
+			expect(result).toEqual(items);
+		});
+
+		it("should work with different property types", () => {
+			const items = [
+				{ code: "A", value: 1 },
+				{ code: "B", value: 2 },
+				{ code: "A", value: 3 },
+			];
+			const result = collections.uniqueObjectsByKey(items, "code");
+			expect(result).toHaveLength(2);
+			expect(result[0].code).toBe("A");
+			expect(result[1].code).toBe("B");
+		});
+
+		it("should handle null items gracefully", () => {
+			const items: Array<{ id: number; name: string } | null> = [
+				{ id: 1, name: "Alice" },
+				null,
+				{ id: 2, name: "Bob" },
+			];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(3);
+			expect(result[0]).toEqual({ id: 1, name: "Alice" });
+			expect(result[1]).toBe(null);
+			expect(result[2]).toEqual({ id: 2, name: "Bob" });
+		});
+
+		it("should group multiple null items together", () => {
+			const items: Array<{ id: number; name: string } | null> = [
+				{ id: 1, name: "Alice" },
+				null,
+				{ id: 2, name: "Bob" },
+				null,
+				null,
+			];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(3);
+			expect(result.filter((item) => item === null)).toHaveLength(1);
+			expect(result[0]).toEqual({ id: 1, name: "Alice" });
+			expect(result[1]).toBe(null);
+			expect(result[2]).toEqual({ id: 2, name: "Bob" });
+		});
+
+		it("should handle undefined items gracefully", () => {
+			const items: Array<{ id: number; name: string } | undefined> = [
+				{ id: 1, name: "Alice" },
+				undefined,
+				{ id: 2, name: "Bob" },
+			];
+			const result = collections.uniqueObjectsByKey(items, "id");
+			expect(result).toHaveLength(3);
+		});
+
+		it("should handle numeric keys", () => {
+			const items = [
+				{ count: 5, label: "first" },
+				{ count: 10, label: "second" },
+				{ count: 5, label: "third" },
+			];
+			const result = collections.uniqueObjectsByKey(items, "count");
+			expect(result).toHaveLength(2);
+			expect(result[0].count).toBe(5);
+			expect(result[1].count).toBe(10);
+		});
+
+		it("should handle boolean keys", () => {
+			const items = [
+				{ active: true, id: 1 },
+				{ active: false, id: 2 },
+				{ active: true, id: 3 },
+			];
+			const result = collections.uniqueObjectsByKey(items, "active");
+			expect(result).toHaveLength(2);
+			expect(result[0].active).toBe(true);
+			expect(result[1].active).toBe(false);
+		});
+	});
+
+	describe("uniqueObjectsBy", () => {
+		it("should remove duplicates using custom selector function", () => {
+			const items = [
+				{ firstName: "Alice", lastName: "Smith" },
+				{ firstName: "Bob", lastName: "Jones" },
+				{ firstName: "Alice", lastName: "Brown" },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) => obj.firstName);
+			expect(result).toHaveLength(2);
+			expect(result[0].firstName).toBe("Alice");
+			expect(result[1].firstName).toBe("Bob");
+		});
+
+		it("should handle complex key generation", () => {
+			const items = [
+				{ firstName: "Alice", lastName: "Smith" },
+				{ firstName: "Bob", lastName: "Jones" },
+				{ firstName: "Alice", lastName: "Smith" },
+			];
+			const result = collections.uniqueObjectsBy(
+				items,
+				(obj) => `${obj.firstName}-${obj.lastName}`,
+			);
+			expect(result).toHaveLength(2);
+		});
+
+		it("should keep last occurrence when duplicates exist", () => {
+			const items = [
+				{ id: 1, category: "A", value: "first" },
+				{ id: 2, category: "A", value: "second" },
+				{ id: 3, category: "B", value: "third" },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) => obj.category);
+			expect(result).toHaveLength(2);
+			expect(result[0].value).toBe("second");
+			expect(result[1].value).toBe("third");
+		});
+
+		it("should handle empty array", () => {
+			const items: { id: number }[] = [];
+			const result = collections.uniqueObjectsBy(items, (obj) => String(obj.id));
+			expect(result).toEqual([]);
+		});
+
+		it("should handle array with single item", () => {
+			const items = [{ id: 1, name: "Alice" }];
+			const result = collections.uniqueObjectsBy(items, (obj) => String(obj.id));
+			expect(result).toHaveLength(1);
+			expect(result[0]).toEqual({ id: 1, name: "Alice" });
+		});
+
+		it("should handle all unique items", () => {
+			const items = [
+				{ id: 1, name: "Alice" },
+				{ id: 2, name: "Bob" },
+				{ id: 3, name: "Charlie" },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) => String(obj.id));
+			expect(result).toHaveLength(3);
+			expect(result).toEqual(items);
+		});
+
+		it("should work with transformed values", () => {
+			const items = [
+				{ email: "Alice@Example.com" },
+				{ email: "bob@example.com" },
+				{ email: "alice@example.com" },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) => obj.email.toLowerCase());
+			expect(result).toHaveLength(2);
+		});
+
+		it("should handle complex object transformations", () => {
+			const items = [
+				{ x: 1, y: 2 },
+				{ x: 3, y: 4 },
+				{ x: 1, y: 2 },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) => `${obj.x},${obj.y}`);
+			expect(result).toHaveLength(2);
+		});
+
+		it("should handle numeric return from selector", () => {
+			const items = [
+				{ id: 1, value: 100 },
+				{ id: 2, value: 200 },
+				{ id: 3, value: 100 },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) => String(obj.value));
+			expect(result).toHaveLength(2);
+		});
+
+		it("should deduplicate based on computed values", () => {
+			const items = [
+				{ price: 10, quantity: 2 },
+				{ price: 5, quantity: 4 },
+				{ price: 20, quantity: 1 },
+			];
+			const result = collections.uniqueObjectsBy(items, (obj) =>
+				String(obj.price * obj.quantity),
+			);
+			expect(result).toHaveLength(1); // All have total of 20
+		});
+	});
+});

package/tests/extensibility/extension.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { extension } from "../../src/extensibility/extension.js";
+
+class Host {
+	public static instance = new Host();
+	public n = 0;
+
+	public bump(amount: number): number {
+		this.n += amount;
+		return this.n;
+	}
+}
+
+class HostExtensions {
+	@extension(Host, { static: true })
+	public static grow(host: Host, amount: number): number {
+		return host.bump(amount);
+	}
+}
+
+void HostExtensions;
+
+describe("extension({ static: true })", () => {
+	it("installs a constructor method that runs on the singleton", () => {
+		Host.instance.n = 0;
+		expect((Host as unknown as { grow: (amount: number) => number }).grow(2)).toBe(2);
+		expect(Host.instance.n).toBe(2);
+	});
+});