@decohere/core 0.0.1-dev.116

package/commonjs/src/semver/semver.js

@@ -0,0 +1,92 @@
+"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 Semver () {
+        return Semver;
+    },
+    get SemverError () {
+        return SemverError;
+    },
+    get VersionTypes () {
+        return VersionTypes;
+    }
+});
+const VersionTypes = {
+    major: "major",
+    minor: "minor",
+    patch: "patch",
+    prerelease: "prerelease"
+};
+class SemverError extends Error {
+    constructor(message){
+        super(message);
+        this.name = SemverError.name;
+    }
+}
+const SEMVER_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+class Semver {
+    version;
+    constructor(version){
+        this.ensureValid(version);
+        this.version = version;
+    }
+    increment(versionType, preid = "pre") {
+        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;
+    }
+    toString() {
+        return this.version;
+    }
+    ensureValid(version) {
+        if (SEMVER_REGEX.test(version)) {
+            return;
+        }
+        throw new SemverError(`Invalid semantic version: ${version}`);
+    }
+    parse(version) {
+        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/commonjs/src/system/camel-case.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "lowerCamelCase", {
+    enumerable: true,
+    get: function() {
+        return lowerCamelCase;
+    }
+});
+function lowerCamelCase(val) {
+    return String(val).charAt(0).toLowerCase() + String(val).slice(1);
+}

package/commonjs/src/system/debounce.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "debounce", {
+    enumerable: true,
+    get: function() {
+        return debounce;
+    }
+});
+function debounce(callback, delay) {
+    let timeoutTimer;
+    return (...args)=>{
+        clearTimeout(timeoutTimer);
+        timeoutTimer = setTimeout(async ()=>{
+            await callback(...args);
+        }, delay);
+    };
+}

package/commonjs/src/system/decorator.js

@@ -0,0 +1,46 @@
+"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 FunctionDecorator () {
+        return FunctionDecorator;
+    },
+    get ignoreDuringUnitTest () {
+        return ignoreDuringUnitTest;
+    },
+    get ignoreIf () {
+        return ignoreIf;
+    }
+});
+class FunctionDecorator {
+    options;
+    constructor(){
+        this.decoratorFactory = this.decoratorFactory.bind(this);
+    }
+    decoratorFactory(options) {
+        this.options = options;
+        return this.decorator.bind(this);
+    }
+}
+function ignoreIf(...envVars) {
+    return (_, __, descriptor)=>{
+        const originalFunction = descriptor.value;
+        descriptor.value = function(target, key, descriptor) {
+            if (envVars.some((v)=>process.env[v] === "true")) {
+                return descriptor;
+            }
+            return originalFunction.bind(this)(target, key, descriptor);
+        };
+        return descriptor;
+    };
+}
+function ignoreDuringUnitTest() {
+    return ignoreIf("TEST");
+}

package/commonjs/src/system/environment.js

@@ -0,0 +1,23 @@
+"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 DefaultEnvironment () {
+        return DefaultEnvironment;
+    },
+    get Environments () {
+        return Environments;
+    }
+});
+const Environments = {
+    production: "production",
+    development: "development"
+};
+const DefaultEnvironment = Environments.development;

package/commonjs/src/system/function.types.js

@@ -0,0 +1,18 @@
+/**
+ * Generic function type that can replace arrow function signatures.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: (arg1: string, arg2: number) => boolean
+ * type MyCallback = Func<[string, number], boolean>;
+ *
+ * // Instead of: (data: any) => void
+ * type MyHandler = Func<[any], void>;
+ *
+ * // Instead of: () => Promise<string>
+ * type MyAsyncFunc = Func<[], Promise<string>>;
+ * ```
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/commonjs/src/system/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./camel-case.js"), exports);
+_export_star(require("./debounce.js"), exports);
+_export_star(require("./decorator.js"), exports);
+_export_star(require("./environment.js"), exports);
+_export_star(require("./function.types.js"), exports);
+_export_star(require("./retry.decorator.js"), exports);
+_export_star(require("./type.utils.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/system/retry.decorator.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "retry", {
+    enumerable: true,
+    get: function() {
+        return retry;
+    }
+});
+const _decorator = require("./decorator.js");
+const _sleep = require("./sleep.js");
+class RetryDecorator extends _decorator.FunctionDecorator {
+    decorator(_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        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) {
+            let lastError;
+            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 (0, _sleep.sleep)(delayMs);
+                    }
+                }
+            }
+            throw lastError;
+        };
+        return descriptor;
+    }
+}
+const retry = new RetryDecorator().decoratorFactory;

package/commonjs/src/system/sleep.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "sleep", {
+    enumerable: true,
+    get: function() {
+        return sleep;
+    }
+});
+const sleep = (ms)=>new Promise((resolve)=>setTimeout(()=>{
+            resolve(null);
+        }, ms));

package/commonjs/src/system/type.utils.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/commonjs/src/testing/flush-promises.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "flushPromises", {
+    enumerable: true,
+    get: function() {
+        return flushPromises;
+    }
+});
+var scheduler = typeof setImmediate === "function" ? setImmediate : setTimeout;
+function flushPromises() {
+    return new Promise((resolve)=>{
+        scheduler(resolve);
+    });
+}

package/commonjs/src/testing/glob-with-memfs.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "withMemfsFsForGlob", {
+    enumerable: true,
+    get: function() {
+        return withMemfsFsForGlob;
+    }
+});
+const _memfs = require("memfs");
+function withMemfsFsForGlob(actual) {
+    // Preserve all module exports, overriding only `glob` to force `{ fs: memfs }`.
+    const glob = (pattern, options)=>actual.glob(pattern, {
+            ...options,
+            fs: _memfs.fs
+        });
+    return {
+        ...actual,
+        glob
+    };
+}

package/commonjs/src/testing/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./flush-promises.js"), exports);
+_export_star(require("./glob-with-memfs.js"), exports);
+_export_star(require("./memfs.js"), exports);
+_export_star(require("./mock-logger.js"), exports);
+_export_star(require("./spy-on-constructor.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/testing/memfs.js

@@ -0,0 +1,52 @@
+"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 createTestFile () {
+        return createTestFile;
+    },
+    get fileExists () {
+        return fileExists;
+    },
+    get readFile () {
+        return readFile;
+    },
+    get resetMemfs () {
+        return resetMemfs;
+    },
+    get seedMemfs () {
+        return seedMemfs;
+    }
+});
+const _memfs = require("memfs");
+function resetMemfs() {
+    _memfs.vol.reset();
+}
+function seedMemfs(files) {
+    _memfs.vol.fromJSON(files);
+}
+function createTestFile(filePath, content) {
+    _memfs.fs.mkdirSync(filePath.substring(0, filePath.lastIndexOf("/")), {
+        recursive: true
+    });
+    _memfs.fs.writeFileSync(filePath, content);
+}
+async function readFile(filePath) {
+    const response = await _memfs.fs.promises.readFile(filePath, "utf8");
+    return response;
+}
+function fileExists(filePath) {
+    try {
+        _memfs.vol.statSync(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+}

package/commonjs/src/testing/mock-logger.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "createMockLogger", {
+    enumerable: true,
+    get: function() {
+        return createMockLogger;
+    }
+});
+const _vitest = require("vitest");
+const DefaultLogLevels = {
+    fatal: 60,
+    error: 50,
+    warn: 40,
+    info: 30,
+    debug: 20,
+    trace: 10
+};
+function createMockLogger() {
+    return {
+        error: _vitest.vi.fn(),
+        info: _vitest.vi.fn(),
+        warn: _vitest.vi.fn(),
+        debug: _vitest.vi.fn(),
+        trace: _vitest.vi.fn(),
+        fatal: _vitest.vi.fn(),
+        isLevelEnabled: _vitest.vi.fn().mockReturnValue(true),
+        get currentLevel () {
+            return "info";
+        },
+        get logLevels () {
+            return DefaultLogLevels;
+        }
+    };
+}

package/commonjs/src/testing/spy-on-constructor.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "spyOnConstructor", {
+    enumerable: true,
+    get: function() {
+        return spyOnConstructor;
+    }
+});
+const _vitest = require("vitest");
+function spyOnConstructor(Target) {
+    const spy = _vitest.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
+    };
+}

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

@@ -0,0 +1,82 @@
+import { NodeCacheAdapter } from "./node-cache-memoize.adapter.js";
+export 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 = NodeCacheAdapter.create({
+                enableMemoization: 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}`;
+    }
+}
+/**
+ * Singleton instance of the cache manager
+ */ export const Caching = new CacheManager();

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

@@ -0,0 +1,51 @@
+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);
+}
+import { isPromise } from "node:util/types";
+import { FunctionDecorator, ignoreIf } from "../system/decorator.js";
+import { Caching } from "./cache-manager.js";
+export class CacheDecorator extends FunctionDecorator {
+    decorator(_target, propertyKey, descriptor) {
+        const cacheInstance = this.options?.cache ?? Caching.getCache(this.options?.name);
+        const keyFn = this.options?.keyFn;
+        const originalMethod = descriptor.value;
+        const wrapped = function(...args) {
+            const cacheKey = keyFn ? keyFn(...args) : Caching.generateCacheKey(this, propertyKey, args);
+            if (cacheInstance.has(cacheKey)) {
+                const val = cacheInstance.get(cacheKey);
+                return val;
+            }
+            const resultOrPromise = originalMethod.apply(this, args);
+            if (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([
+    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);
+export const cache = new CacheDecorator().decoratorFactory;

package/es6/src/caching/cache.js

@@ -0,0 +1,3 @@
+/**
+ * Interface for cache implementations used by the @cache() decorator
+ */ export { };

package/es6/src/caching/index.js

@@ -0,0 +1,6 @@
+export * from "./cache.decorator.js";
+export * from "./cache.js";
+export * from "./cache-manager.js";
+export * from "./invalidate-cache.decorator.js";
+export * from "./memoize.decorator.js";
+export * from "./node-cache-memoize.adapter.js";