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

package/src/reflection/types/reflection.types.ts

@@ -0,0 +1,28 @@
+export type Constructable<T extends object = object> = {
+	new (...args: any[]): T;
+} & Type;
+
+export type Field = {
+	key: string;
+	propertyDescriptor: PropertyDescriptor;
+};
+
+export type FunctionType = (
+	...args: unknown[]
+) => unknown | unknown[] | undefined | Promise<unknown>;
+export type ReflectMeta = "paramtypes" | "type";
+
+export const MetaDataOwners = {
+	Hearth: "hearth",
+	Reflect: "design",
+} satisfies Record<string, string>;
+
+export const ReflectionMeta = {
+	paramtypes: `${MetaDataOwners.Reflect}:paramtypes`,
+	type: `${MetaDataOwners.Reflect}:type`,
+} satisfies Record<ReflectMeta, string>;
+
+export type Type = {
+	prototype: object;
+	name?: string;
+};

package/src/reflection/utilities.ts

@@ -0,0 +1,92 @@
+import {
+	type Constructable,
+	type Field,
+	type FunctionType,
+	ReflectionMeta,
+	type Type,
+} from "./types/reflection.types.js";
+
+const Primitives = ["string", "number", "bigint", "boolean", "undefined", "symbol", "null"];
+
+export const isPrimitiveOrDateType = (type: Type) => {
+	return Primitives.includes(type.name.toLocaleLowerCase()) || isDateType(type);
+};
+
+export const isDateType = (type: Type) => {
+	return type?.prototype === Date.prototype;
+};
+
+export function isConstructable(
+	type: Constructable | object | FunctionType,
+): type is Constructable {
+	const proto = (type as Constructable)?.prototype;
+	const isConstructable = typeof type === "function" && typeof proto === "object";
+	return isConstructable;
+}
+export const isArrayType = (type: Type) => {
+	return type?.prototype === Array.prototype;
+};
+export function getMeta<T>(key: string, target: object, propertyKey?: string) {
+	const meta = Reflect.getMetadata(key, target, propertyKey) as T;
+	return meta;
+}
+export function getFunctions(object: Constructable) {
+	const functions = Object.entries(Object.getOwnPropertyDescriptors(object.prototype))
+		.filter(([key]) => key !== "constructor")
+		.map(([, value]) => value);
+
+	return functions;
+}
+export function getFunction(object: Constructable, functionName: string) {
+	const [, value] = Object.entries(Object.getOwnPropertyDescriptors(object.prototype)).find(
+		([k]) => k !== "constructor" && k === functionName,
+	);
+
+	return value;
+}
+export function getFunctionMetadata<T>(key: string, target: object, func: FunctionType) {
+	const meta = Reflect.getMetadata(key, target, func.name) as T;
+	return meta;
+}
+export function getFunctionArgs(target: object, func: FunctionType): Type[] {
+	const meta = getFunctionMetadata<Type[]>(ReflectionMeta.paramtypes, target, func);
+	return meta;
+}
+
+/**
+ * @description Gets the fields from an object
+ * @param object
+ * @returns
+ */
+export function getFields<T>(object: T) {
+	const fields = Object.entries(Object.getOwnPropertyDescriptors(object))
+		.filter(([, val]) => typeof val.value !== "function")
+		.map<Field>(([key, propertyDescriptor]) => ({ key, propertyDescriptor }));
+	return fields;
+}
+export function getFieldType(target: object, fieldName: string) {
+	return Reflect.getMetadata(ReflectionMeta.type, target, fieldName) as Type;
+}
+export function getArgumentMeta<T>(key: string, target: FunctionType, argIndex: number) {
+	const meta = Reflect.getMetadata(key, target, argIndex.toString()) as T;
+	return meta;
+}
+export function defineMeta<T>(key: string, value: T, target: object) {
+	Reflect.defineMetadata(key, value, target);
+}
+/**
+ * @description Facade function to define metadata for a function argument
+ * @param key
+ * @param value
+ * @param func
+ * @param argIndex
+ */
+
+export function defineArgumentMeta<T>(
+	key: string,
+	value: T,
+	func: FunctionType,
+	argIndex: number,
+) {
+	Reflect.defineMetadata(key, value, func, argIndex.toString());
+}

package/src/semver/index.ts

@@ -0,0 +1 @@
+export * from "./semver.js";

package/src/semver/semver.ts

@@ -0,0 +1,96 @@
+export type VersionType = "major" | "minor" | "patch" | "prerelease";
+
+export const VersionTypes = {
+	major: "major",
+	minor: "minor",
+	patch: "patch",
+	prerelease: "prerelease",
+} satisfies Record<string, VersionType>;
+
+export class SemverError extends Error {
+	public constructor(message: string) {
+		super(message);
+		this.name = SemverError.name;
+	}
+}
+
+const SEMVER_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+type SemverParts = {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease?: string;
+};
+
+export class Semver {
+	private version: string;
+
+	public constructor(version: string) {
+		this.ensureValid(version);
+		this.version = version;
+	}
+
+	public increment(versionType: VersionType, preid = "pre"): Semver {
+		const { major, minor, patch, prerelease } = this.parse(this.version);
+
+		if (versionType === "major") {
+			this.version = `${major + 1}.0.0`;
+			return this;
+		}
+
+		if (versionType === "minor") {
+			this.version = `${major}.${minor + 1}.0`;
+			return this;
+		}
+
+		if (versionType === "patch") {
+			this.version = `${major}.${minor}.${patch + 1}`;
+			return this;
+		}
+
+		if (prerelease == null) {
+			this.version = `${major}.${minor}.${patch + 1}-${preid}.0`;
+			return this;
+		}
+
+		const [identifier, ...rest] = prerelease.split(".");
+		const maybeCounter = rest.at(-1);
+		const counter = maybeCounter != null ? Number.parseInt(maybeCounter, 10) : Number.NaN;
+		if (identifier === preid && Number.isFinite(counter)) {
+			const nextCounter = counter + 1;
+			const prefix = rest.length > 1 ? `${rest.slice(0, -1).join(".")}.` : "";
+			this.version = `${major}.${minor}.${patch}-${preid}.${prefix}${nextCounter}`;
+			return this;
+		}
+
+		this.version = `${major}.${minor}.${patch}-${preid}.0`;
+		return this;
+	}
+
+	public toString(): string {
+		return this.version;
+	}
+
+	private ensureValid(version: string): void {
+		if (SEMVER_REGEX.test(version)) {
+			return;
+		}
+
+		throw new SemverError(`Invalid semantic version: ${version}`);
+	}
+
+	private parse(version: string): SemverParts {
+		const match = version.match(SEMVER_REGEX);
+		if (match == null) {
+			throw new SemverError(`Invalid semantic version: ${version}`);
+		}
+
+		return {
+			major: Number.parseInt(match[1], 10),
+			minor: Number.parseInt(match[2], 10),
+			patch: Number.parseInt(match[3], 10),
+			prerelease: match[4],
+		};
+	}
+}

package/src/system/camel-case.ts

@@ -0,0 +1,3 @@
+export function lowerCamelCase(val) {
+	return String(val).charAt(0).toLowerCase() + String(val).slice(1);
+}

package/src/system/debounce.ts

@@ -0,0 +1,13 @@
+export function debounce<T extends unknown[]>(
+	callback: (...args: T) => Promise<void>,
+	delay: number,
+) {
+	let timeoutTimer: ReturnType<typeof setTimeout>;
+
+	return (...args: T) => {
+		clearTimeout(timeoutTimer);
+		timeoutTimer = setTimeout(async () => {
+			await callback(...args);
+		}, delay);
+	};
+}

package/src/system/decorator.ts

@@ -0,0 +1,41 @@
+export abstract class FunctionDecorator<TOptions = undefined> {
+	protected options: TOptions;
+	public constructor() {
+		this.decoratorFactory = this.decoratorFactory.bind(this);
+	}
+
+	public abstract decorator(
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	);
+
+	public decoratorFactory(options?: TOptions) {
+		this.options = options;
+		return this.decorator.bind(this);
+	}
+}
+
+/**
+ * Skips the decorated method decorator if any of the named environment variables equal "true".
+ * Useful for disabling decorators like @cache() during unit tests or via feature flags.
+ *
+ * @example @ignoreIf("TEST", "DISABLE_CACHE")
+ */
+export function ignoreIf(...envVars: string[]) {
+	return (_: object, __: string, descriptor: PropertyDescriptor) => {
+		const originalFunction = descriptor.value;
+		descriptor.value = function (target: object, key: string, descriptor: PropertyDescriptor) {
+			if (envVars.some((v) => process.env[v] === "true")) {
+				return descriptor;
+			}
+			return originalFunction.bind(this)(target, key, descriptor);
+		};
+		return descriptor;
+	};
+}
+
+/** @deprecated Use ignoreIf("TEST") instead */
+export function ignoreDuringUnitTest() {
+	return ignoreIf("TEST");
+}

package/src/system/environment.ts

@@ -0,0 +1,6 @@
+export type Environment = "production" | "development";
+export const Environments = {
+	production: "production",
+	development: "development",
+} satisfies Record<string, Environment>;
+export const DefaultEnvironment = Environments.development;

package/{types/src/system/function.types.d.ts → src/system/function.types.ts}

@@ -13,7 +13,10 @@
  * type MyAsyncFunc = Func<[], Promise<string>>;
  * ```
  */
-export type Func<TArgs extends readonly unknown[] = [], TReturn = void> = (...args: TArgs) => TReturn;
+export type Func<TArgs extends readonly unknown[] = [], TReturn = void> = (
+	...args: TArgs
+) => TReturn;
+
 /**
  * Async function type that returns a Promise.
  *
@@ -26,7 +29,11 @@ export type Func<TArgs extends readonly unknown[] = [], TReturn = void> = (...ar
  * type InitFunc = AsyncFunc<[], void>;
  * ```
  */
-export type AsyncFunc<TArgs extends readonly unknown[] = [], TReturn = void> = Func<TArgs, Promise<TReturn>>;
+export type AsyncFunc<TArgs extends readonly unknown[] = [], TReturn = void> = Func<
+	TArgs,
+	Promise<TReturn>
+>;
+
 /**
  * Predicate function type that returns a boolean.
  *
@@ -40,6 +47,7 @@ export type AsyncFunc<TArgs extends readonly unknown[] = [], TReturn = void> = F
  * ```
  */
 export type Predicate<TArgs extends readonly unknown[] = []> = Func<TArgs, boolean>;
+
 /**
  * Action function type that returns void.
  *

package/src/system/retry.decorator.ts

@@ -0,0 +1,43 @@
+import { FunctionDecorator } from "./decorator.js";
+import { sleep } from "./sleep.js";
+
+export type RetryOptions = {
+	attempts?: number;
+	delayMs?: number;
+	shouldRetry?: (error: unknown) => boolean;
+};
+
+class RetryDecorator extends FunctionDecorator<RetryOptions> {
+	public decorator(_target: object, _propertyKey: string, descriptor: PropertyDescriptor) {
+		const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+		const attempts = Math.max(1, this.options?.attempts ?? 3);
+		const delayMs = Math.max(0, this.options?.delayMs ?? 0);
+		const shouldRetry = this.options?.shouldRetry ?? (() => true);
+
+		descriptor.value = async function (...args: unknown[]) {
+			let lastError: unknown;
+
+			for (let attempt = 1; attempt <= attempts; attempt++) {
+				try {
+					return await Promise.resolve(originalMethod.apply(this, args));
+				} catch (error) {
+					lastError = error;
+					const shouldAttemptAgain = attempt < attempts && shouldRetry(error);
+					if (!shouldAttemptAgain) {
+						throw error;
+					}
+
+					if (delayMs > 0) {
+						await sleep(delayMs);
+					}
+				}
+			}
+
+			throw lastError;
+		};
+
+		return descriptor;
+	}
+}
+
+export const retry = new RetryDecorator().decoratorFactory;

package/src/system/sleep.ts

@@ -0,0 +1,6 @@
+export const sleep = (ms: number) =>
+	new Promise((resolve) =>
+		setTimeout(() => {
+			resolve(null);
+		}, ms),
+	);

package/src/system/type.utils.ts

@@ -0,0 +1,5 @@
+export type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (
+	x: infer I,
+) => void
+	? I
+	: never;

package/src/testing/flush-promises.ts

@@ -0,0 +1,7 @@
+var scheduler = typeof setImmediate === "function" ? setImmediate : setTimeout;
+
+export function flushPromises() {
+	return new Promise((resolve) => {
+		scheduler(resolve);
+	});
+}

package/src/testing/glob-with-memfs.ts

@@ -0,0 +1,25 @@
+import { fs } from "memfs";
+
+// Wraps a real `glob` module so all file-system access is routed through memfs.
+//
+// Why this exists:
+// - Integration tests often need real glob matching semantics.
+// - Vitest `vi.mock` factories are hoisted, so directly importing and patching
+//   `glob` inside helper modules can trigger initialization-order issues.
+// - Passing the already-loaded `actual` module keeps the helper pure and
+//   hoist-safe while still allowing us to inject memfs.
+export function withMemfsFsForGlob<
+	TGlobModule extends { glob: (...args: unknown[]) => unknown },
+>(actual: TGlobModule): TGlobModule {
+	// Preserve all module exports, overriding only `glob` to force `{ fs: memfs }`.
+	const glob = ((pattern: string | string[], options?: unknown) =>
+		(actual.glob as (...args: unknown[]) => unknown)(pattern, {
+			...(options as Record<string, unknown> | undefined),
+			fs,
+		})) as TGlobModule["glob"];
+
+	return {
+		...actual,
+		glob,
+	};
+}

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+export * from "./flush-promises.js";
+export * from "./glob-with-memfs.js";
+export * from "./memfs.js";
+export * from "./mock-logger.js";
+export * from "./spy-on-constructor.js";

package/src/testing/memfs.ts

@@ -0,0 +1,28 @@
+import { fs, vol } from "memfs";
+
+export function resetMemfs(): void {
+	vol.reset();
+}
+
+export function seedMemfs(files: Record<string, string>): void {
+	vol.fromJSON(files);
+}
+
+export function createTestFile(filePath: string, content: string | Buffer): void {
+	fs.mkdirSync(filePath.substring(0, filePath.lastIndexOf("/")), { recursive: true });
+	fs.writeFileSync(filePath, content);
+}
+
+export async function readFile(filePath: string): Promise<string> {
+	const response = (await fs.promises.readFile(filePath, "utf8")) as string;
+	return response;
+}
+
+export function fileExists(filePath: string): boolean {
+	try {
+		vol.statSync(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/testing/mock-logger.ts

@@ -0,0 +1,42 @@
+import { vi } from "vitest";
+
+export type LoggerMethod = (msg: string | number | object, ...args: unknown[]) => void;
+
+export type TestLogger = {
+	fatal: LoggerMethod;
+	error: LoggerMethod;
+	warn: LoggerMethod;
+	info: LoggerMethod;
+	debug: LoggerMethod;
+	trace: LoggerMethod;
+	isLevelEnabled(level: string): boolean;
+	readonly currentLevel: string;
+	readonly logLevels: Record<string, number>;
+};
+
+const DefaultLogLevels: Record<string, number> = {
+	fatal: 60,
+	error: 50,
+	warn: 40,
+	info: 30,
+	debug: 20,
+	trace: 10,
+};
+
+export function createMockLogger(): TestLogger {
+	return {
+		error: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		debug: vi.fn(),
+		trace: vi.fn(),
+		fatal: vi.fn(),
+		isLevelEnabled: vi.fn().mockReturnValue(true),
+		get currentLevel() {
+			return "info";
+		},
+		get logLevels() {
+			return DefaultLogLevels;
+		},
+	};
+}

package/src/testing/spy-on-constructor.ts

@@ -0,0 +1,33 @@
+import { vi } from "vitest";
+import type { Constructable } from "../reflection/index.js";
+
+/**
+ * Creates a Proxy around a class constructor that intercepts `new` calls,
+ * records arguments via a spy, and delegates to the real constructor.
+ *
+ * Use this to assert what was injected into a class by a DI container
+ * (e.g. Container) without changing actual behavior.
+ *
+ * The proxy copies all `reflect-metadata` entries from the original class
+ * so that DI metadata (`design:paramtypes`) remains intact.
+ *
+ * @example
+ * const { spy, Proxy: SpiedService } = spyOnConstructor(MyService);
+ * // use SpiedService in place of MyService when wiring the container
+ * expect(spy).toHaveBeenCalledWith(expect.any(ExpectedDependency));
+ */
+export function spyOnConstructor<T extends Constructable>(
+	Target: T,
+): { spy: ReturnType<typeof vi.fn>; Proxy: T } {
+	const spy = vi.fn();
+	const ProxiedTarget = new Proxy(Target, {
+		construct(Ctor, args) {
+			spy(...args);
+			return Reflect.construct(Ctor, args);
+		},
+	});
+	for (const key of Reflect.getMetadataKeys(Target)) {
+		Reflect.defineMetadata(key, Reflect.getMetadata(key, Target), ProxiedTarget);
+	}
+	return { spy, Proxy: ProxiedTarget as T };
+}

package/tests/caching/cache-manager.spec.ts

@@ -0,0 +1,147 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { ICache } from "../../src/caching/cache.js";
+import { Caching } from "../../src/caching/cache-manager.js";
+
+// Simple cache implementation for testing
+class TestCache implements ICache {
+	public get isMemoize(): boolean {
+		throw new Error("Method not implemented.");
+	}
+	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();
+	}
+}
+
+describe("Caching manager", () => {
+	afterEach(() => {
+		Caching.flushAllCaches();
+	});
+
+	describe("setCache and getCache", () => {
+		it("should set and get a named cache instance", () => {
+			const testCache = new TestCache();
+			Caching.setCache("TEST_CACHE", testCache);
+
+			const retrieved = Caching.getCache("TEST_CACHE");
+			expect(retrieved).toBe(testCache);
+		});
+
+		it("should create default cache if not set", () => {
+			const defaultCache = Caching.getCache();
+			expect(defaultCache).toBeDefined();
+
+			// Should return the same instance on subsequent calls
+			const defaultCache2 = Caching.getCache();
+			expect(defaultCache2).toBe(defaultCache);
+		});
+
+		it("should create default cache when getting by 'DEFAULT' name", () => {
+			const defaultCache = Caching.getCache("DEFAULT");
+			expect(defaultCache).toBeDefined();
+
+			const defaultCache2 = Caching.getCache();
+			expect(defaultCache2).toBe(defaultCache);
+		});
+
+		it("should maintain separate cache instances for different names", () => {
+			const cache1 = new TestCache();
+			const cache2 = new TestCache();
+
+			Caching.setCache("CACHE_1", cache1);
+			Caching.setCache("CACHE_2", cache2);
+
+			expect(Caching.getCache("CACHE_1")).toBe(cache1);
+			expect(Caching.getCache("CACHE_2")).toBe(cache2);
+			expect(Caching.getCache("CACHE_1")).not.toBe(cache2);
+		});
+	});
+
+	describe("hasCache", () => {
+		it("should return true for existing cache", () => {
+			const testCache = new TestCache();
+			Caching.setCache("TEST_CACHE", testCache);
+
+			expect(Caching.hasCache("TEST_CACHE")).toBe(true);
+		});
+
+		it("should return false for non-existing cache", () => {
+			expect(Caching.hasCache("NON_EXISTENT")).toBe(false);
+		});
+
+		it("should return true for default cache after first access", () => {
+			Caching.getCache(); // This creates the default cache
+			expect(Caching.hasCache("DEFAULT")).toBe(true);
+		});
+	});
+
+	describe("clear", () => {
+		it("should clear a named cache if it has a clear method", () => {
+			const testCache = new TestCache();
+			Caching.setCache("TEST_CACHE", testCache);
+
+			const cache = Caching.getCache("TEST_CACHE");
+			cache.set("key1", "value1");
+			expect(cache.get("key1")).toBe("value1");
+
+			Caching.flushAllCaches();
+			expect(cache.get("key1")).toBeUndefined();
+		});
+
+		it("should clear default cache when no name is provided", () => {
+			const cache = Caching.getCache();
+			cache.set("key1", "value1");
+			expect(cache.get("key1")).toBe("value1");
+
+			Caching.flushAllCaches();
+			expect(cache.get("key1")).toBeUndefined();
+		});
+	});
+
+	describe("removeCache", () => {
+		it("should remove a cache instance", () => {
+			const testCache = new TestCache();
+			Caching.setCache("TEST_CACHE", testCache);
+
+			expect(Caching.hasCache("TEST_CACHE")).toBe(true);
+
+			Caching.removeCache("TEST_CACHE");
+			expect(Caching.hasCache("TEST_CACHE")).toBe(false);
+		});
+
+		it("should not throw error when removing non-existent cache", () => {
+			expect(() => Caching.removeCache("NON_EXISTENT")).not.toThrow();
+		});
+
+		it("should allow re-adding cache after removal", () => {
+			const testCache1 = new TestCache();
+			const testCache2 = new TestCache();
+
+			Caching.setCache("TEST_CACHE", testCache1);
+			expect(Caching.getCache("TEST_CACHE")).toBe(testCache1);
+
+			Caching.removeCache("TEST_CACHE");
+			expect(Caching.hasCache("TEST_CACHE")).toBe(false);
+
+			Caching.setCache("TEST_CACHE", testCache2);
+			expect(Caching.getCache("TEST_CACHE")).toBe(testCache2);
+		});
+	});
+});