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

package/tests/system/decorator.spec.ts

@@ -0,0 +1,250 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { FunctionDecorator, ignoreDuringUnitTest } from "../../src/system/decorator.js";
+
+// Test decorator class
+class TestDecorator extends FunctionDecorator {
+	@ignoreDuringUnitTest()
+	public decorator(
+		_target: object,
+		_propertyKey: string,
+		descriptor: PropertyDescriptor,
+	): PropertyDescriptor {
+		const originalMethod = descriptor.value;
+		descriptor.value = function (...args: unknown[]) {
+			// Add "decorated-" prefix to show decorator was applied
+			const result = originalMethod.apply(this, args);
+			return `decorated-${result}`;
+		};
+		return descriptor;
+	}
+}
+
+// Another test decorator without @ignoreInUnitTest
+class AlwaysActiveDecorator extends FunctionDecorator {
+	public decorator(_target: object, _propertyKey: string, descriptor: PropertyDescriptor) {
+		const originalMethod = descriptor.value;
+		descriptor.value = function (...args: unknown[]) {
+			const result = originalMethod.apply(this, args);
+			return `always-${result}`;
+		};
+		return descriptor;
+	}
+}
+
+const createTestDecorator = new TestDecorator().decoratorFactory;
+const createAlwaysActiveDecorator = new AlwaysActiveDecorator().decoratorFactory;
+
+describe("ignoreInUnitTest decorator", () => {
+	let originalTestEnv: string | undefined;
+
+	beforeEach(() => {
+		originalTestEnv = process.env.TEST;
+	});
+
+	afterEach(() => {
+		if (originalTestEnv !== undefined) {
+			process.env.TEST = originalTestEnv;
+		} else {
+			delete process.env.TEST;
+		}
+	});
+
+	describe("when TEST environment variable is not set", () => {
+		beforeEach(() => {
+			delete process.env.TEST;
+		});
+
+		it("should apply decorator normally", () => {
+			class TestClass {
+				@createTestDecorator()
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance = new TestClass();
+			const result = instance.getValue();
+
+			expect(result).toBe("decorated-original");
+		});
+	});
+
+	describe("when TEST=false", () => {
+		beforeEach(() => {
+			process.env.TEST = "false";
+		});
+
+		it("should apply decorator normally", () => {
+			class TestClass {
+				@createTestDecorator()
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance = new TestClass();
+			const result = instance.getValue();
+
+			expect(result).toBe("decorated-original");
+		});
+	});
+
+	describe("when TEST=true", () => {
+		beforeEach(() => {
+			process.env.TEST = "true";
+		});
+
+		it("should disable decorator and return original function", () => {
+			class TestClass {
+				@createTestDecorator()
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance = new TestClass();
+			const result = instance.getValue();
+
+			expect(result).toBe("original"); // No decoration applied
+		});
+
+		it("should still apply decorators that are not marked with @ignoreInUnitTest", () => {
+			class TestClass {
+				@createAlwaysActiveDecorator()
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance = new TestClass();
+			const result = instance.getValue();
+
+			expect(result).toBe("always-original"); // Decoration still applied
+		});
+	});
+
+	describe("multiple decorators", () => {
+		it("should disable decorator when marked with @ignoreInUnitTest when TEST=true", () => {
+			process.env.TEST = "true";
+
+			class TestClass {
+				@createTestDecorator() // This will be disabled and return original function
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance = new TestClass();
+			const result = instance.getValue();
+
+			// When a decorator with @ignoreInUnitTest is disabled, it returns the original function
+			expect(result).toBe("original");
+		});
+
+		it("should work with multiple decorators where some have @ignoreInUnitTest", () => {
+			process.env.TEST = "true";
+
+			// Test with the non-ignored decorator applied first
+			class TestClass1 {
+				@createAlwaysActiveDecorator() // This will be active
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			// Test with the ignored decorator applied first
+			class TestClass2 {
+				@createTestDecorator() // This will be disabled
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance1 = new TestClass1();
+			const instance2 = new TestClass2();
+
+			expect(instance1.getValue()).toBe("always-original");
+			expect(instance2.getValue()).toBe("original");
+		});
+
+		it("should apply all decorators when TEST is not true", () => {
+			delete process.env.TEST;
+
+			class TestClass {
+				@createTestDecorator() // This will be active
+				@createAlwaysActiveDecorator() // This will be active
+				public getValue(): string {
+					return "original";
+				}
+			}
+
+			const instance = new TestClass();
+			const result = instance.getValue();
+
+			// Both decorators should be applied (decorators apply bottom-to-top)
+			expect(result).toBe("decorated-always-original");
+		});
+	});
+
+	describe("FunctionDecorator base class", () => {
+		it("should bind decoratorFactory method correctly", () => {
+			const decorator = new TestDecorator();
+			const factory = decorator.decoratorFactory;
+
+			expect(typeof factory).toBe("function");
+			expect(factory).toBe(decorator.decoratorFactory);
+		});
+
+		it("should return the decorator method from decoratorFactory", () => {
+			const decorator = new TestDecorator();
+			const factory = decorator.decoratorFactory();
+
+			expect(typeof factory).toBe("function");
+		});
+	});
+
+	describe("ignoreDuringUnitTest function behavior", () => {
+		it("should wrap decorator methods to respect TEST environment variable", () => {
+			// Create a mock decorator method
+			const originalDecoratorMethod = vi.fn((_target, _key, descriptor) => {
+				const originalMethod = descriptor.value;
+				descriptor.value = function (...args: unknown[]) {
+					return `decorated-${originalMethod.apply(this, args)}`;
+				};
+				return descriptor;
+			});
+
+			const mockDescriptor = {
+				value: originalDecoratorMethod,
+			};
+
+			// Apply @ignoreDuringUnitTest to the decorator method
+			ignoreDuringUnitTest()({}, "testMethod", mockDescriptor);
+
+			// Create a test target and method to decorate
+			const testTarget = {};
+			const testPropertyKey = "testMethod";
+			const testMethodDescriptor = {
+				value: () => "original",
+			};
+
+			// When TEST is not set, should call original decorator method
+			delete process.env.TEST;
+			const result1 = mockDescriptor.value(testTarget, testPropertyKey, testMethodDescriptor);
+			expect(originalDecoratorMethod).toHaveBeenCalledWith(
+				testTarget,
+				testPropertyKey,
+				testMethodDescriptor,
+			);
+			expect(result1).toBe(testMethodDescriptor); // Original decorator modifies descriptor in place
+
+			// When TEST=true, should return descriptor unchanged (no-op behavior)
+			process.env.TEST = "true";
+			originalDecoratorMethod.mockClear();
+			const originalDescriptor = { value: () => "untouched" };
+			const result2 = mockDescriptor.value(testTarget, testPropertyKey, originalDescriptor);
+			expect(originalDecoratorMethod).not.toHaveBeenCalled();
+			expect(result2).toBe(originalDescriptor); // Should return descriptor unchanged
+		});
+	});
+});

package/tests/system/retry.decorator.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from "vitest";
+import { retry } from "../../src/system/retry.decorator.js";
+
+describe("retry decorator", () => {
+	it("retries until success within attempt limit", async () => {
+		class TestClass {
+			private attempts = 0;
+
+			@retry({ attempts: 3 })
+			public async unstableOperation() {
+				this.attempts++;
+				if (this.attempts < 3) {
+					throw new Error("transient");
+				}
+				return "ok";
+			}
+		}
+
+		const instance = new TestClass();
+		await expect(instance.unstableOperation()).resolves.toBe("ok");
+	});
+
+	it("throws after max attempts", async () => {
+		class TestClass {
+			@retry({ attempts: 2 })
+			public async alwaysFails() {
+				throw new Error("persistent");
+			}
+		}
+
+		const instance = new TestClass();
+		await expect(instance.alwaysFails()).rejects.toThrow("persistent");
+	});
+
+	it("respects shouldRetry predicate", async () => {
+		const shouldRetry = vi.fn((error: unknown) => {
+			return (error as Error).message !== "fatal";
+		});
+
+		class TestClass {
+			private attempts = 0;
+
+			@retry({ attempts: 5, shouldRetry })
+			public async operation() {
+				this.attempts++;
+				if (this.attempts === 1) {
+					throw new Error("fatal");
+				}
+				return "ok";
+			}
+		}
+
+		const instance = new TestClass();
+		await expect(instance.operation()).rejects.toThrow("fatal");
+		expect(shouldRetry).toHaveBeenCalledTimes(1);
+	});
+});

package/LICENSE

@@ -1,15 +0,0 @@
-ISC License
-
-Copyright (c) 2025-2026 Typesmiths
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/commonjs/src/caching/cache-manager.js

@@ -1,98 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get Caches () {
-        return Caches;
-    },
-    get Caching () {
-        return Caching;
-    }
-});
-const _mapcache = require("./map-cache.js");
-const Caches = {
-    default: "DEFAULT",
-    memoize: "MEMOIZE_CACHE"
-};
-/**
- * Central cache manager for managing named cache instances
- */ class CacheManager {
-    caches = new Map();
-    defaultCacheName = Caches.default;
-    /**
-	 * Set a cache instance with the given name
-	 * @param name - The name of the cache
-	 * @param cache - The cache instance
-	 */ setCache(name, cache) {
-        this.caches.set(name, cache);
-    }
-    /**
-	 * Get a cache instance by name
-	 * @param name - The name of the cache, defaults to "DEFAULT"
-	 * @returns The cache instance
-	 */ getCache(name, memoize = false) {
-        const cacheName = name ?? this.defaultCacheName;
-        if (!this.caches.has(cacheName)) {
-            const cache = new _mapcache.MapCache({
-                memoize
-            });
-            this.caches.set(cacheName, cache);
-        }
-        return this.caches.get(cacheName);
-    }
-    /**
-	 * Clear a cache by name. If no name is provided, clears the default cache.
-	 * Note: This only works if the cache implements a clear() method.
-	 * @param name - The name of the cache to clear
-	 */ flush(name) {
-        const cacheName = name ?? this.defaultCacheName;
-        const cache = this.caches.get(cacheName);
-        cache.flushAll();
-    }
-    flushAllCaches() {
-        for (const [, cache] of this.caches){
-            cache.flushAll();
-        }
-    }
-    /**
-	 * Remove a cache instance by name
-	 * @param name - The name of the cache to remove
-	 */ removeCache(name) {
-        this.caches.delete(name);
-    }
-    /**
-	 * Check if a cache with the given name exists
-	 * @param name - The name of the cache
-	 * @returns True if the cache exists, false otherwise
-	 */ hasCache(name) {
-        return this.caches.has(name);
-    }
-    instanceIds = new WeakMap();
-    instanceIdCounter = 0;
-    /**
-	 * Generate a cache key for a given instance, function name, and arguments.
-	 * Each instance receives a stable numeric ID so cache entries are never
-	 * shared across instances of the same class.
-	 * @param instance - The class instance (`this` at call time)
-	 * @param functionName - The name of the decorated method
-	 * @param args - The method arguments
-	 * @returns A unique cache key string
-	 */ generateCacheKey(instance, functionName, args) {
-        if (!this.instanceIds.has(instance)) {
-            this.instanceIds.set(instance, ++this.instanceIdCounter);
-        }
-        const instanceId = this.instanceIds.get(instance);
-        const argsStr = JSON.stringify({
-            args
-        }, (_key, val)=>typeof val === "function" ? `[Function:${val.name}]` : val);
-        return `${instance.constructor.name}#${instanceId}|${functionName}|${argsStr}`;
-    }
-}
-const Caching = new CacheManager();

package/commonjs/src/caching/cache.decorator.js

@@ -1,69 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get CacheDecorator () {
-        return CacheDecorator;
-    },
-    get cache () {
-        return cache;
-    }
-});
-const _types = require("node:util/types");
-const _decorator = require("../system/decorator.js");
-const _cachemanager = require("./cache-manager.js");
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-class CacheDecorator extends _decorator.FunctionDecorator {
-    decorator(_target, propertyKey, descriptor) {
-        const cacheInstance = this.options?.cache ?? _cachemanager.Caching.getCache(this.options?.name);
-        const keyFn = this.options?.keyFn;
-        const originalMethod = descriptor.value;
-        const wrapped = function(...args) {
-            const cacheKey = keyFn ? keyFn(...args) : _cachemanager.Caching.generateCacheKey(this, propertyKey, args);
-            if (cacheInstance.has(cacheKey)) {
-                const val = cacheInstance.get(cacheKey);
-                return val;
-            }
-            const resultOrPromise = originalMethod.apply(this, args);
-            if ((0, _types.isPromise)(resultOrPromise)) {
-                resultOrPromise.then((result)=>{
-                    cacheInstance.set(cacheKey, result);
-                }, ()=>{
-                /* rejection propagates via the returned promise */ });
-            } else {
-                cacheInstance.set(cacheKey, resultOrPromise);
-            }
-            return resultOrPromise;
-        };
-        Object.defineProperty(wrapped, "name", {
-            value: propertyKey
-        });
-        descriptor.value = wrapped;
-    }
-}
-_ts_decorate([
-    (0, _decorator.ignoreIf)("FORGE_DISABLE_CACHE"),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        Object,
-        String,
-        typeof PropertyDescriptor === "undefined" ? Object : PropertyDescriptor
-    ]),
-    _ts_metadata("design:returntype", void 0)
-], CacheDecorator.prototype, "decorator", null);
-const cache = new CacheDecorator().decoratorFactory;

package/commonjs/src/caching/cache.js

@@ -1,6 +0,0 @@
-/**
- * Interface for cache implementations used by the @cache() decorator
- */ "use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});

package/commonjs/src/caching/index.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-_export_star(require("./cache.decorator.js"), exports);
-_export_star(require("./cache.js"), exports);
-_export_star(require("./cache-manager.js"), exports);
-_export_star(require("./invalidate-cache.decorator.js"), exports);
-_export_star(require("./memoize.decorator.js"), exports);
-_export_star(require("./map-cache.js"), exports);
-function _export_star(from, to) {
-    Object.keys(from).forEach(function(k) {
-        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
-            Object.defineProperty(to, k, {
-                enumerable: true,
-                get: function() {
-                    return from[k];
-                }
-            });
-        }
-    });
-    return from;
-}

package/commonjs/src/caching/invalidate-cache.decorator.js

@@ -1,92 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get InvalidateCacheDecorator () {
-        return InvalidateCacheDecorator;
-    },
-    get invalidateCache () {
-        return invalidateCache;
-    },
-    get invalidateMemoize () {
-        return invalidateMemoize;
-    }
-});
-const _types = require("node:util/types");
-const _decorator = require("../system/decorator.js");
-const _cachemanager = require("./cache-manager.js");
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-class InvalidateCacheDecorator extends _decorator.FunctionDecorator {
-    decorator(_target, _propertyKey, descriptor) {
-        const { getKey, cache, name } = this.options;
-        const cacheInstance = cache ?? _cachemanager.Caching.getCache(name);
-        const originalMethod = descriptor.value;
-        descriptor.value = function(...args) {
-            const resultOrPromise = originalMethod.apply(this, args);
-            const evict = ()=>{
-                const key = getKey(this, args);
-                cacheInstance.del(key);
-            };
-            if ((0, _types.isPromise)(resultOrPromise)) {
-                resultOrPromise.then(evict);
-            } else {
-                evict();
-            }
-            return resultOrPromise;
-        };
-    }
-}
-_ts_decorate([
-    (0, _decorator.ignoreIf)("FORGE_DISABLE_CACHE"),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        Object,
-        String,
-        typeof PropertyDescriptor === "undefined" ? Object : PropertyDescriptor
-    ]),
-    _ts_metadata("design:returntype", void 0)
-], InvalidateCacheDecorator.prototype, "decorator", null);
-const buildGetKey = (method, keyFn)=>{
-    if (typeof method === "string") return ()=>method;
-    if (keyFn) return (_instance, args)=>keyFn(...args);
-    return (instance, args)=>_cachemanager.Caching.generateCacheKey(instance, method.name, args);
-};
-const invalidateCache = (method, options)=>{
-    const cache = options?.cache ?? _cachemanager.Caching.getCache(options?.name);
-    return new InvalidateCacheDecorator().decoratorFactory({
-        getKey: buildGetKey(method, options?.keyFn),
-        ...options,
-        cache
-    });
-};
-invalidateCache.evict = (instance, method, args = [])=>{
-    const key = _cachemanager.Caching.generateCacheKey(instance, method.name, args);
-    _cachemanager.Caching.getCache().del(key);
-};
-const invalidateMemoize = (method, options)=>{
-    const cache = options?.cache ?? _cachemanager.Caching.getCache(options?.name ?? _cachemanager.Caches.memoize, true);
-    return new InvalidateCacheDecorator().decoratorFactory({
-        getKey: buildGetKey(method),
-        ...options,
-        cache
-    });
-};
-invalidateMemoize.evict = (instance, method, args = [])=>{
-    const key = _cachemanager.Caching.generateCacheKey(instance, method.name, args);
-    _cachemanager.Caching.getCache(_cachemanager.Caches.memoize, true).del(key);
-};

package/commonjs/src/caching/map-cache.js

@@ -1,39 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "MapCache", {
-    enumerable: true,
-    get: function() {
-        return MapCache;
-    }
-});
-class MapCache {
-    #entries = new Map();
-    #memoize;
-    constructor(options = {}){
-        this.#memoize = options.memoize ?? false;
-    }
-    get isMemoize() {
-        return this.#memoize;
-    }
-    get(key) {
-        const value = this.#entries.get(key);
-        if (this.#memoize || value === null || typeof value !== "object") {
-            return value;
-        }
-        return structuredClone(value);
-    }
-    set(key, value) {
-        this.#entries.set(key, value);
-    }
-    has(key) {
-        return this.#entries.has(key);
-    }
-    del(key) {
-        this.#entries.delete(key);
-    }
-    flushAll() {
-        this.#entries.clear();
-    }
-}

package/commonjs/src/caching/memoize.decorator.js

@@ -1,36 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get MemoizeDecorator () {
-        return MemoizeDecorator;
-    },
-    get memoize () {
-        return memoize;
-    }
-});
-const _cachedecorator = require("./cache.decorator.js");
-const _cachemanager = require("./cache-manager.js");
-class MemoizeDecorator extends _cachedecorator.CacheDecorator {
-    decorator(target, propertyKey, descriptor) {
-        const cache = this.options?.cache ?? _cachemanager.Caching.getCache(this.options?.name ?? _cachemanager.Caches.memoize, true);
-        if (!cache.isMemoize) {
-            throw new Error("Memoize decorator requires a cache that supports memoization (stores references, not clones)");
-        }
-        // Pass the resolved cache to the base class by updating options
-        // This ensures the base class uses CacheNames.memoize when no cache was provided
-        this.options = {
-            ...this.options,
-            cache
-        };
-        return super.decorator(target, propertyKey, descriptor);
-    }
-}
-const memoize = new MemoizeDecorator().decoratorFactory;