@decohere/core 0.0.1-dev.116

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

@@ -0,0 +1,71 @@
+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 { Caches, Caching } from "./cache-manager.js";
+export class InvalidateCacheDecorator extends FunctionDecorator {
+    decorator(_target, _propertyKey, descriptor) {
+        const { getKey, cache, name } = this.options;
+        const cacheInstance = cache ?? 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 (isPromise(resultOrPromise)) {
+                resultOrPromise.then(evict);
+            } else {
+                evict();
+            }
+            return resultOrPromise;
+        };
+    }
+}
+_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)
+], InvalidateCacheDecorator.prototype, "decorator", null);
+const buildGetKey = (method, keyFn)=>{
+    if (typeof method === "string") return ()=>method;
+    if (keyFn) return (_instance, args)=>keyFn(...args);
+    return (instance, args)=>Caching.generateCacheKey(instance, method.name, args);
+};
+export const invalidateCache = (method, options)=>{
+    const cache = options?.cache ?? Caching.getCache(options?.name);
+    return new InvalidateCacheDecorator().decoratorFactory({
+        getKey: buildGetKey(method, options?.keyFn),
+        ...options,
+        cache
+    });
+};
+invalidateCache.evict = (instance, method, args = [])=>{
+    const key = Caching.generateCacheKey(instance, method.name, args);
+    Caching.getCache().del(key);
+};
+export const invalidateMemoize = (method, options)=>{
+    const cache = options?.cache ?? Caching.getCache(options?.name ?? Caches.memoize, true);
+    return new InvalidateCacheDecorator().decoratorFactory({
+        getKey: buildGetKey(method),
+        ...options,
+        cache
+    });
+};
+invalidateMemoize.evict = (instance, method, args = [])=>{
+    const key = Caching.generateCacheKey(instance, method.name, args);
+    Caching.getCache(Caches.memoize, true).del(key);
+};

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

@@ -0,0 +1,27 @@
+import { CacheDecorator } from "./cache.decorator.js";
+import { Caches, Caching } from "./cache-manager.js";
+/**
+ * Memoize decorator class that extends CacheDecorator with memoization support
+ * Automatically uses a memoization-capable cache (NodeCache with useClones: false)
+ */ export class MemoizeDecorator extends CacheDecorator {
+    decorator(target, propertyKey, descriptor) {
+        const cache = this.options?.cache ?? Caching.getCache(this.options?.name ?? 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);
+    }
+}
+/**
+ * Memoize decorator factory
+ * Provides true memoization by storing object references instead of clones
+ *
+ * @param options - Optional configuration for the memoize decorator
+ * @returns Decorator function
+ */ export const memoize = new MemoizeDecorator().decoratorFactory;

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

@@ -0,0 +1,37 @@
+import NodeCache from "@cacheable/node-cache";
+/**
+ * NodeCache adapter configured for memoization (useClones: false)
+ * This allows storing object references instead of clones for true memoization
+ */ export class NodeCacheAdapter {
+    static create(options = {
+        enableMemoization: false
+    }) {
+        const nodeCache = new NodeCache({
+            useClones: !options.enableMemoization
+        });
+        return new NodeCacheAdapter(nodeCache);
+    }
+    supportsMemoization = true;
+    cache;
+    constructor(inst = new NodeCache()){
+        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/es6/src/cli/action.js

@@ -0,0 +1,47 @@
+export const ActionMap = Symbol("ActionMap");
+export 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/es6/src/cli/command.js

@@ -0,0 +1,106 @@
+import { Command as CommanderType } from "commander";
+export const CommandResponse = {
+    success (_ctx, responses) {
+        return responses;
+    },
+    help () {
+        return {};
+    },
+    fromAction (name, response) {
+        return {
+            [name]: response
+        };
+    }
+};
+/** Thrown when a command execution fails due to action errors. */ export class CommandError extends Error {
+}
+export class DecohereCommand extends CommanderType {
+    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/es6/src/cli/index.js

@@ -0,0 +1,4 @@
+export { ActionMap, ActionResponse } from "./action.js";
+export { CommandError, CommandResponse, DecohereCommand } from "./command.js";
+export { ModuleManifest } from "./module.type.js";
+export { ConfigFileOption, ConfigurationOption, DryRunOption, EnvFileIfExistsOption, EnvFileOption, LogLevelOption, NoBuildOptions, NoCleanOptions, ProjectOption } from "./options.js";

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

@@ -0,0 +1,11 @@
+/**
+ * Simple declaration interface for a CLI module.
+ * Extend this and implement the four abstract members.
+ */ export 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);
+    }
+}

package/es6/src/cli/options.js

@@ -0,0 +1,76 @@
+import { Option } from "commander";
+function parseOptionalBoolean(input) {
+    if (typeof input === "boolean") {
+        return input;
+    }
+    const value = input.trim().toLowerCase();
+    if ([
+        "true",
+        "1",
+        "yes",
+        "on"
+    ].includes(value)) {
+        return true;
+    }
+    if ([
+        "false",
+        "0",
+        "no",
+        "off"
+    ].includes(value)) {
+        return false;
+    }
+    throw new Error(`Invalid boolean value: "${input}". Use true/false.`);
+}
+export class ConfigurationOption extends Option {
+    constructor(defaultValue){
+        super("--configuration <configuration>", "Configuration name");
+        this.default(defaultValue);
+    }
+}
+export class ConfigFileOption extends Option {
+    constructor(defaultValue = ".decohere.js"){
+        super("--config-file <file>", "Path to Decohere config file");
+        this.default(defaultValue);
+    }
+}
+export class LogLevelOption extends Option {
+    constructor(){
+        super("--log-level <level>", "Log level (trace, debug, info, warn, error)");
+    }
+}
+export class EnvFileOption extends Option {
+    constructor(){
+        super("--env-file <file>", "Load environment variables from this file before running");
+    }
+}
+export class EnvFileIfExistsOption extends Option {
+    constructor(){
+        super("--env-file-if-exists <file>", "Like --env-file, but skip it when the file is missing");
+    }
+}
+export class NoCleanOptions extends Option {
+    constructor(defaultValue){
+        super("--no-clean", "Will not clean the project directories");
+        this.default(defaultValue);
+    }
+}
+export class NoBuildOptions extends Option {
+    constructor(defaultValue){
+        super("--no-build", "Will not run the build step");
+        this.default(defaultValue);
+    }
+}
+export class DryRunOption extends Option {
+    constructor(description, defaultValue = false){
+        super("--dry-run [dryRun]", description);
+        this.default(defaultValue);
+        this.preset(true);
+        this.argParser(parseOptionalBoolean);
+    }
+}
+export class ProjectOption extends Option {
+    constructor(){
+        super("--project <project>", "Project name to target");
+    }
+}

package/es6/src/collections/collections.js

@@ -0,0 +1,4 @@
+export * from "./find-duplicates.js";
+export * from "./merge-arrays.js";
+export * from "./sum.js";
+export * from "./unique-objects.js";

package/es6/src/collections/find-duplicates.js

@@ -0,0 +1,17 @@
+export function findDuplicatesByKey(items, key) {
+    return findDuplicatesBy(items, (item)=>String(item[key]));
+}
+export function findDuplicatesBy(items, selector) {
+    const groups = new Map();
+    for (const item of items){
+        const k = selector(item);
+        const existing = groups.get(k) ?? [];
+        groups.set(k, [
+            ...existing,
+            item
+        ]);
+    }
+    return [
+        ...groups.entries()
+    ].filter(([, group])=>group.length > 1);
+}

package/es6/src/collections/index.js

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

package/es6/src/collections/merge-arrays.js

@@ -0,0 +1,16 @@
+export function mergeByKey(first, second, key) {
+    return mergeBy(first, second, (item)=>String(item[key]));
+}
+export function mergeBy(first, second, selector) {
+    // Second collection values win when keys collide.
+    const merged = [
+        ...first,
+        ...second
+    ];
+    return [
+        ...new Map(merged.map((item)=>[
+                selector(item),
+                item
+            ])).values()
+    ];
+}

package/es6/src/collections/sum.js

@@ -0,0 +1,45 @@
+export function sumByKey(objects, key) {
+    return sum(objects, key);
+}
+export function sumBy(objects, key) {
+    return sum(objects, key);
+}
+function extractValueFromItem(item, key) {
+    if (typeof key === "function") {
+        const result = key(item);
+        return isNumericValue(result) ? result : 0;
+    }
+    const value = item?.[key];
+    return isNumericValue(value) ? value : 0;
+}
+function isNumericValue(value) {
+    return typeof value === "number" || typeof value === "bigint";
+}
+function determineSumType(firstValue) {
+    return typeof firstValue === "bigint" ? "bigint" : "number";
+}
+function getInitialSumValue(sumType) {
+    return sumType === "bigint" ? 0n : 0;
+}
+function addValues(total, value, sumType) {
+    if (sumType === "bigint") {
+        const totalBigInt = total;
+        const valueBigInt = typeof value === "bigint" ? value : BigInt(value);
+        return totalBigInt + valueBigInt;
+    }
+    const totalNumber = total;
+    const valueNumber = typeof value === "number" ? value : Number(value);
+    return totalNumber + valueNumber;
+}
+function sum(objects, key) {
+    if (objects.length === 0) {
+        return 0;
+    }
+    const firstValue = extractValueFromItem(objects[0], key);
+    const sumType = determineSumType(firstValue);
+    const initialValue = getInitialSumValue(sumType);
+    return objects.reduce((total, item)=>{
+        const value = extractValueFromItem(item, key);
+        return addValues(total, value, sumType);
+    }, initialValue);
+}

package/es6/src/collections/unique-objects.js

@@ -0,0 +1,21 @@
+export function uniqueObjectsByKey(objects, key) {
+    return uniqueObjects(objects, key);
+}
+export function uniqueObjectsBy(objects, key) {
+    return uniqueObjects(objects, key);
+}
+function uniqueObjects(objects, key) {
+    const getKey = (key, item)=>{
+        if (typeof key === "function") {
+            return key(item);
+        }
+        return item != null ? item[key] : null;
+    };
+    const arrayUniqueByKey = [
+        ...new Map(objects.map((item)=>[
+                getKey(key, item),
+                item
+            ])).values()
+    ];
+    return arrayUniqueByKey;
+}

package/es6/src/composition/index.js

@@ -0,0 +1 @@
+export { };

package/es6/src/configuration/configuration.types.js

@@ -0,0 +1 @@
+export const ConfigurationServiceToken = Symbol("IConfigurationService");

package/es6/src/configuration/index.js

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

package/es6/src/diagnostics/index.js

@@ -0,0 +1 @@
+export { Trace, timed, trace } from "./trace.js";

package/es6/src/diagnostics/trace.js

@@ -0,0 +1,68 @@
+import { isPromise } from "node:util/types";
+import { ConsoleAdapter, scribe } from "@decohere/scribe";
+// Keep existing behavior for now: trace mode is toggled via FORGE_TRACE.
+const isTraceEnabled = process.env.FORGE_TRACE != null;
+if (isTraceEnabled) {
+    const hasExplicitLevel = process.env.LOG_LEVEL != null || process.env.SCRIBE_LOG_LEVEL != null || process.env.LOGGING_LEVEL != null;
+    if (!hasExplicitLevel) {
+        scribe.configure({
+            adapter: new ConsoleAdapter(),
+            options: {
+                logLevel: "trace"
+            }
+        });
+    }
+}
+function serializeArgs(args) {
+    if (args.length === 0) return "";
+    return args.map((arg)=>{
+        if (Array.isArray(arg)) return `[${arg.map(String).join(", ")}]`;
+        const s = String(arg);
+        return s.length > 60 ? `${s.slice(0, 57)}...` : s;
+    }).join(", ");
+}
+function wrapWithTiming(fn, className, methodName, logLevel) {
+    let logger;
+    return function(...args) {
+        if (logger == null) {
+            logger = scribe.logger(className);
+        }
+        const log = logger;
+        const label = `${methodName}(${serializeArgs(args)})`;
+        const start = performance.now();
+        const logDuration = ()=>{
+            log[logLevel](`${label}: ${(performance.now() - start).toFixed(2)}ms`);
+        };
+        const result = fn.apply(this, args);
+        if (isPromise(result)) {
+            return result.finally(logDuration);
+        }
+        logDuration();
+        return result;
+    };
+}
+export function trace(target, propertyKey, descriptor) {
+    if (!isTraceEnabled) return descriptor;
+    const className = target.constructor.name;
+    descriptor.value = wrapWithTiming(descriptor.value, className, propertyKey, "trace");
+    return descriptor;
+}
+/**
+ * Always-on method timing. Logs duration at `info` regardless of `FORGE_TRACE`.
+ * Use this to time a specific method without raising the process log level.
+ */ export function timed(target, propertyKey, descriptor) {
+    const className = target.constructor.name;
+    descriptor.value = wrapWithTiming(descriptor.value, className, propertyKey, "info");
+    return descriptor;
+}
+export function Trace(constructor) {
+    if (!isTraceEnabled) return;
+    const className = constructor.name;
+    for (const key of Object.getOwnPropertyNames(constructor.prototype)){
+        if (key === "constructor") continue;
+        const descriptor = Object.getOwnPropertyDescriptor(constructor.prototype, key);
+        if (descriptor == null || typeof descriptor.value !== "function") continue;
+        descriptor.value = wrapWithTiming(descriptor.value, className, key, "trace");
+        Object.defineProperty(constructor.prototype, key, descriptor);
+    }
+}

package/es6/src/extensibility/decorator-factory-base.js

@@ -0,0 +1,39 @@
+/**
+ * Base class for creating decorator factory instances with methods that can be
+ * conditionally disabled during unit testing.
+ *
+ * Example usage:
+ * ```typescript
+ * class MyDecoratorFactory extends DecoratorFactory {
+ *   @ignoreInUnitTest
+ *   cache(options?: CacheOptions) {
+ *     return cache(options);
+ *   }
+ *
+ *   @ignoreInUnitTest
+ *   logger(options?: LoggerOptions) {
+ *     return logger(options);
+ *   }
+ * }
+ *
+ * const decorators = new MyDecoratorFactory();
+ *
+ * class TestClass {
+ *   @decorators.cache({ ttl: 1000 })
+ *   async getData() {
+ *     // This decorator will be disabled when TEST=true
+ *   }
+ * }
+ * ```
+ */ export class DecoratorFactoryBase {
+    /**
+	 * Utility method to check if we're currently in a test environment
+	 */ isTestEnvironment() {
+        return process.env.TEST === "true";
+    }
+    /**
+	 * Creates a no-op decorator that returns the original function unchanged
+	 */ createNoOpDecorator() {
+        return (_target, _propertyKey, descriptor)=>descriptor;
+    }
+}

package/es6/src/extensibility/decorator-factory.js

@@ -0,0 +1,21 @@
+/**
+ * Decorator factory class that provides decorator methods which can be conditionally
+ * disabled during unit testing using the @ignoreInUnitTest decorator.
+ *
+ * Inspired by: https://jasonharper.blog/2018/03/13/decorate-the-decorator-to-exclude-in-unit-testing/
+ */ /**
+ * Decorator that disables the decorated decorator method when TEST environment variable is true.
+ * If TEST=true, it returns a no-op decorator that simply returns the original function unchanged.
+ */ export function ignoreInUnitTest(_target, _propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = function(...args) {
+        // Check if we're in a test environment
+        if (process.env.TEST === "true") {
+            // Return a no-op decorator that just returns the original function
+            return (originalFunction)=>originalFunction;
+        }
+        // Otherwise, apply the original decorator method
+        return originalMethod.apply(this, args);
+    };
+    return descriptor;
+}

package/es6/src/extensibility/extension.js

@@ -0,0 +1,27 @@
+export function extension(ctor, options) {
+    return (_target, propertyKey, descriptor)=>{
+        const originalFunction = descriptor.value;
+        ctor.prototype[propertyKey] = function(...args) {
+            return originalFunction.apply(this, [
+                this,
+                ...args
+            ]);
+        };
+        if (options?.static) {
+            Object.defineProperty(ctor, propertyKey, {
+                configurable: true,
+                writable: true,
+                value (...args) {
+                    const receiver = singletonOf(ctor) ?? this;
+                    return originalFunction.apply(receiver, [
+                        receiver,
+                        ...args
+                    ]);
+                }
+            });
+        }
+    };
+}
+function singletonOf(ctor) {
+    return ctor.instance;
+}

package/es6/src/extensibility/index.js

@@ -0,0 +1,6 @@
+export * from "./decorator-factory.js";
+export * from "./decorator-factory-base.js";
+export * from "./extension.js";
+export * from "./mixwith.js";
+export * from "./pipeline.js";
+export * from "./step.js";