@decohere/core 0.0.1-dev.116

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

@@ -0,0 +1,98 @@
+"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 _nodecachememoizeadapter = require("./node-cache-memoize.adapter.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 = _nodecachememoizeadapter.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}`;
+    }
+}
+const Caching = new CacheManager();

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

@@ -0,0 +1,69 @@
+"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

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

package/commonjs/src/caching/index.js

@@ -0,0 +1,23 @@
+"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("./node-cache-memoize.adapter.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

@@ -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 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/memoize.decorator.js

@@ -0,0 +1,36 @@
+"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;

package/commonjs/src/caching/node-cache-memoize.adapter.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "NodeCacheAdapter", {
+    enumerable: true,
+    get: function() {
+        return NodeCacheAdapter;
+    }
+});
+const _nodecache = /*#__PURE__*/ _interop_require_default(require("@cacheable/node-cache"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+class NodeCacheAdapter {
+    static create(options = {
+        enableMemoization: false
+    }) {
+        const nodeCache = new _nodecache.default({
+            useClones: !options.enableMemoization
+        });
+        return new NodeCacheAdapter(nodeCache);
+    }
+    supportsMemoization = true;
+    cache;
+    constructor(inst = new _nodecache.default()){
+        this.cache = inst;
+    }
+    get isMemoize() {
+        return !this.cache.options.useClones;
+    }
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, value) {
+        this.cache.set(key, value);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    del(key) {
+        this.cache.del(key);
+    }
+    flushAll() {
+        this.cache.flushAll();
+    }
+}

package/commonjs/src/cli/action.js

@@ -0,0 +1,65 @@
+"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 ActionMap () {
+        return ActionMap;
+    },
+    get ActionResponse () {
+        return ActionResponse;
+    }
+});
+const ActionMap = Symbol("ActionMap");
+class ActionResponse {
+    static Success(name, data) {
+        return new ActionResponse({
+            name,
+            data,
+            succeeded: true
+        });
+    }
+    static Skipped(name) {
+        return new ActionResponse({
+            name,
+            skipped: true
+        });
+    }
+    static Blocking(name) {
+        return new ActionResponse({
+            name,
+            succeeded: true,
+            blocking: true
+        });
+    }
+    static Error(name, messageOrData, data) {
+        if (Array.isArray(messageOrData)) {
+            const message = messageOrData.filter((r)=>!r.succeeded).map((r)=>r.error ?? "Unknown error").join("\n");
+            return new ActionResponse({
+                name,
+                message,
+                data: messageOrData
+            });
+        }
+        return new ActionResponse({
+            name,
+            message: messageOrData,
+            data
+        });
+    }
+    constructor(data){
+        Object.assign(this, data);
+    }
+    name;
+    succeeded = false;
+    skipped = false;
+    blocking = false;
+    message;
+    data;
+}

package/commonjs/src/cli/command.js

@@ -0,0 +1,127 @@
+"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 CommandError () {
+        return CommandError;
+    },
+    get CommandResponse () {
+        return CommandResponse;
+    },
+    get DecohereCommand () {
+        return DecohereCommand;
+    }
+});
+const _commander = require("commander");
+const CommandResponse = {
+    success (_ctx, responses) {
+        return responses;
+    },
+    help () {
+        return {};
+    },
+    fromAction (name, response) {
+        return {
+            [name]: response
+        };
+    }
+};
+class CommandError extends Error {
+}
+class DecohereCommand extends _commander.Command {
+    get actions() {
+        return [];
+    }
+    constructor(name, handler){
+        super();
+        if (typeof name === "string" || typeof name === "function") {
+            this.name(this.parseCommandName(name));
+        } else {
+            this.name(this.parseCommandName(this.constructor));
+            if (name) {
+                this.registerSubcommand(name, handler);
+            }
+        }
+        if (handler && !this.commands.length) {
+            this.action(handler);
+        }
+        this.exitOverride();
+    }
+    /**
+	 * Whether the command, with these options, runs until it is stopped (`flux serve`,
+	 * `forge build --watch`). The CLI then listens for SIGINT and SIGTERM from the moment it
+	 * starts, so a stop during start-up still shuts down cleanly; other commands keep Node's
+	 * default, where Ctrl+C ends them at once.
+	 */ runsUntilStopped(_options) {
+        return false;
+    }
+    async run(actions, options) {
+        const responses = await this.runActions(actions, options);
+        this.throwOnErrors(responses);
+        return CommandResponse.success(options, responses);
+    }
+    registerSubcommand(commands, onAction) {
+        if (typeof commands === "function") {
+            const instance = new commands(commands, onAction);
+            this.addCommand(instance);
+            if (onAction && !instance.commands.length) {
+                instance.action(onAction);
+            }
+            return;
+        }
+        for (const [key, command] of Object.entries(commands)){
+            const instance = command instanceof DecohereCommand ? command : new command(key, onAction);
+            this.addCommand(instance);
+            if (onAction && !instance.commands.length) {
+                instance.action(onAction);
+            }
+        }
+    }
+    async runActions(actions, options) {
+        const selectedActions = this.getSelectedActions(actions);
+        const responses = {};
+        for (const [actionKey, action] of selectedActions){
+            responses[actionKey] = await action.run(options);
+        }
+        return responses;
+    }
+    getSelectedActions(actions) {
+        if (!this.actions.length) {
+            return [];
+        }
+        const actionEntries = Object.entries(actions);
+        return this.actions.map((ActionClass)=>{
+            const selectedAction = actionEntries.find(([, action])=>action instanceof ActionClass);
+            if (!selectedAction) {
+                throw new CommandError(`${this.name()} command missing action instance for ${ActionClass.name}`);
+            }
+            return selectedAction;
+        });
+    }
+    throwOnErrors(responses) {
+        const failures = Object.entries(responses).filter(([, response])=>{
+            if (!response) {
+                return false;
+            }
+            return !response.succeeded && !response.skipped;
+        });
+        if (!failures.length) {
+            return;
+        }
+        throw new CommandError(`${this.name()} command failed. ${failures.map(([actionName, response])=>`${actionName}: ${response?.message ?? "Unknown error"}`).join("\n")}`);
+    }
+    parseCommandName(stringLike) {
+        const command = typeof stringLike === "string" ? stringLike : stringLike.name?.toLowerCase().replace("command", "") ?? "";
+        if (command === "") {
+            throw new CommandError(`Could not parse command name from ${stringLike.toString()}`);
+        }
+        return command;
+    }
+}

package/commonjs/src/cli/index.js

@@ -0,0 +1,61 @@
+"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 ActionMap () {
+        return _action.ActionMap;
+    },
+    get ActionResponse () {
+        return _action.ActionResponse;
+    },
+    get CommandError () {
+        return _command.CommandError;
+    },
+    get CommandResponse () {
+        return _command.CommandResponse;
+    },
+    get ConfigFileOption () {
+        return _options.ConfigFileOption;
+    },
+    get ConfigurationOption () {
+        return _options.ConfigurationOption;
+    },
+    get DecohereCommand () {
+        return _command.DecohereCommand;
+    },
+    get DryRunOption () {
+        return _options.DryRunOption;
+    },
+    get EnvFileIfExistsOption () {
+        return _options.EnvFileIfExistsOption;
+    },
+    get EnvFileOption () {
+        return _options.EnvFileOption;
+    },
+    get LogLevelOption () {
+        return _options.LogLevelOption;
+    },
+    get ModuleManifest () {
+        return _moduletype.ModuleManifest;
+    },
+    get NoBuildOptions () {
+        return _options.NoBuildOptions;
+    },
+    get NoCleanOptions () {
+        return _options.NoCleanOptions;
+    },
+    get ProjectOption () {
+        return _options.ProjectOption;
+    }
+});
+const _action = require("./action.js");
+const _command = require("./command.js");
+const _moduletype = require("./module.type.js");
+const _options = require("./options.js");

package/commonjs/src/cli/module.type.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "ModuleManifest", {
+    enumerable: true,
+    get: function() {
+        return ModuleManifest;
+    }
+});
+class ModuleManifest {
+    /** Sub-command classes this module contributes. */ commands = {};
+    /** Action classes this module contributes. */ actions = {};
+    /** Register infrastructure services into the DI container. */ registerServices(_builder) {}
+    /** Lazily create a workspace instance. Return null if this module does not use a workspace. */ createWorkspace(_options) {
+        return Promise.resolve(null);
+    }
+}