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

package/package.json

@@ -1,24 +1,17 @@
 {
   "name": "@decohere/core",
-  "version": "0.0.1-dev.125",
-  "description": "The runtime base every Decohere package builds on: reflection, composition, configuration types, extensibility, collections, objects, caching on a Map, and basic file IO. No side effects on import.",
+  "version": "0.0.1-dev.5",
+  "description": "Core utility library — collections, caching, IO, CLI primitives, reflection, and composition",
   "keywords": [
     "typescript",
     "utilities",
-    "reflection",
-    "composition",
+    "collections",
     "caching",
+    "io",
+    "cli",
+    "reflection",
     "decohere"
   ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/core#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/core"
-  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -44,6 +37,11 @@
       "import": "./es6/src/extensibility/index.js",
       "require": "./commonjs/src/extensibility/index.js"
     },
+    "./interop": {
+      "types": "./types/src/interop/index.d.ts",
+      "import": "./es6/src/interop/index.js",
+      "require": "./commonjs/src/interop/index.js"
+    },
     "./io": {
       "types": "./types/src/io/index.d.ts",
       "import": "./es6/src/io/index.js",
@@ -64,18 +62,45 @@
       "import": "./es6/src/system/index.js",
       "require": "./commonjs/src/system/index.js"
     },
+    "./semver": {
+      "types": "./types/src/semver/index.d.ts",
+      "import": "./es6/src/semver/index.js",
+      "require": "./commonjs/src/semver/index.js"
+    },
+    "./testing": {
+      "types": "./types/src/testing/index.d.ts",
+      "import": "./es6/src/testing/index.js",
+      "require": "./commonjs/src/testing/index.js"
+    },
     "./composition": {
       "types": "./types/src/composition/index.d.ts",
       "import": "./es6/src/composition/index.js",
       "require": "./commonjs/src/composition/index.js"
+    },
+    "./cli": {
+      "types": "./types/src/cli/index.d.ts",
+      "import": "./es6/src/cli/index.js",
+      "require": "./commonjs/src/cli/index.js"
+    },
+    "./diagnostics": {
+      "types": "./types/src/diagnostics/index.d.ts",
+      "import": "./es6/src/diagnostics/index.js",
+      "require": "./commonjs/src/diagnostics/index.js"
     }
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/scribe": "0.0.1-dev.125",
+    "@cacheable/node-cache": "^2.0.1",
+    "@decohere/scribe": "0.0.1-dev.5",
+    "commander": "^13.1.0",
+    "glob": "^13.0.1",
+    "picomatch": "^4.0.4",
     "reflect-metadata": "^0.2.2"
   },
-  "devDependencies": {}
+  "devDependencies": {
+    "memfs": "^4.17.0",
+    "vitest": "^3.2.6"
+  }
 }

package/src/caching/cache-manager.ts

@@ -0,0 +1,102 @@
+import type { ICache } from "./cache.js";
+import { NodeCacheAdapter } from "./node-cache-memoize.adapter.js";
+
+export const Caches = {
+	default: "DEFAULT",
+	memoize: "MEMOIZE_CACHE",
+} as const;
+
+/**
+ * Central cache manager for managing named cache instances
+ */
+class CacheManager {
+	private caches = new Map<string, ICache>();
+	private readonly defaultCacheName = Caches.default;
+
+	/**
+	 * Set a cache instance with the given name
+	 * @param name - The name of the cache
+	 * @param cache - The cache instance
+	 */
+	public setCache(name: string, cache: ICache): void {
+		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
+	 */
+	public getCache(name?: string, memoize: boolean = false): ICache {
+		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
+	 */
+	public flush(name?: string): void {
+		const cacheName = name ?? this.defaultCacheName;
+		const cache = this.caches.get(cacheName);
+		cache.flushAll();
+	}
+
+	public flushAllCaches(): void {
+		for (const [, cache] of this.caches) {
+			cache.flushAll();
+		}
+	}
+
+	/**
+	 * Remove a cache instance by name
+	 * @param name - The name of the cache to remove
+	 */
+	public removeCache(name: string): void {
+		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
+	 */
+	public hasCache(name: string): boolean {
+		return this.caches.has(name);
+	}
+
+	private readonly instanceIds = new WeakMap<object, number>();
+	private 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
+	 */
+	public generateCacheKey(instance: object, functionName: string, args: unknown[]): string {
+		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/src/caching/cache.decorator.ts

@@ -0,0 +1,56 @@
+import { isPromise } from "node:util/types";
+import { FunctionDecorator, ignoreIf } from "../system/decorator.js";
+import type { ICache } from "./cache.js";
+import { Caching } from "./cache-manager.js";
+
+/**
+ * Options for configuring the @cache() decorator
+ */
+export interface CacheOptions {
+	cache?: ICache;
+	name?: string;
+	/**
+	 * Custom key function. When provided, replaces the default instance-scoped key
+	 * with a caller-defined key, enabling cross-instance cache sharing.
+	 */
+	keyFn?: (...args: unknown[]) => string;
+}
+
+export class CacheDecorator extends FunctionDecorator<CacheOptions> {
+	@ignoreIf("FORGE_DISABLE_CACHE")
+	public decorator(_target: object, propertyKey: string, descriptor: PropertyDescriptor) {
+		const cacheInstance = this.options?.cache ?? Caching.getCache(this.options?.name);
+		const keyFn = this.options?.keyFn;
+		const originalMethod = descriptor.value;
+
+		const wrapped = function (...args: unknown[]) {
+			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;
+	}
+}
+
+export const cache = new CacheDecorator().decoratorFactory;

package/src/caching/cache.ts

@@ -0,0 +1,11 @@
+/**
+ * Interface for cache implementations used by the @cache() decorator
+ */
+export interface ICache {
+	get(key: string): unknown;
+	set(key: string, value: unknown): void;
+	has(key: string): boolean;
+	del(key: string): void;
+	flushAll();
+	get isMemoize(): boolean;
+}

package/{es6/src/caching/index.js → src/caching/index.ts}

@@ -3,4 +3,4 @@ export * from "./cache.js";
 export * from "./cache-manager.js";
 export * from "./invalidate-cache.decorator.js";
 export * from "./memoize.decorator.js";
-export * from "./map-cache.js";
+export * from "./node-cache-memoize.adapter.js";

package/src/caching/invalidate-cache.decorator.ts

@@ -0,0 +1,81 @@
+import { isPromise } from "node:util/types";
+import { FunctionDecorator, ignoreIf } from "../system/decorator.js";
+import type { CacheOptions } from "./cache.decorator.js";
+import { Caches, Caching } from "./cache-manager.js";
+
+type InvalidateCacheOptions = CacheOptions & {
+	getKey: (instance: object, args: unknown[]) => string;
+};
+
+export class InvalidateCacheDecorator extends FunctionDecorator<InvalidateCacheOptions> {
+	@ignoreIf("FORGE_DISABLE_CACHE")
+	public decorator(_target: object, _propertyKey: string, descriptor: PropertyDescriptor) {
+		const { getKey, cache, name } = this.options;
+		const cacheInstance = cache ?? Caching.getCache(name);
+		const originalMethod = descriptor.value;
+
+		descriptor.value = function (...args: unknown[]) {
+			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;
+		};
+	}
+}
+
+const buildGetKey = (
+	method: string | ((...args: never[]) => unknown),
+	keyFn?: (...args: unknown[]) => string,
+) => {
+	if (typeof method === "string") return () => method;
+	if (keyFn) return (_instance: object, args: unknown[]) => keyFn(...args);
+	return (instance: object, args: unknown[]) =>
+		Caching.generateCacheKey(instance, method.name, args);
+};
+
+export const invalidateCache = (
+	method: string | ((...args: never[]) => unknown),
+	options?: CacheOptions,
+) => {
+	const cache = options?.cache ?? Caching.getCache(options?.name);
+	return new InvalidateCacheDecorator().decoratorFactory({
+		getKey: buildGetKey(method, options?.keyFn),
+		...options,
+		cache,
+	});
+};
+invalidateCache.evict = (
+	instance: object,
+	method: (...args: never[]) => unknown,
+	args: unknown[] = [],
+) => {
+	const key = Caching.generateCacheKey(instance, method.name, args);
+	Caching.getCache().del(key);
+};
+
+export const invalidateMemoize = (
+	method: string | ((...args: never[]) => unknown),
+	options?: CacheOptions,
+) => {
+	const cache = options?.cache ?? Caching.getCache(options?.name ?? Caches.memoize, true);
+	return new InvalidateCacheDecorator().decoratorFactory({
+		getKey: buildGetKey(method),
+		...options,
+		cache,
+	});
+};
+invalidateMemoize.evict = (
+	instance: object,
+	method: (...args: never[]) => unknown,
+	args: unknown[] = [],
+) => {
+	const key = Caching.generateCacheKey(instance, method.name, args);
+	Caching.getCache(Caches.memoize, true).del(key);
+};

package/src/caching/memoize.decorator.ts

@@ -0,0 +1,34 @@
+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 {
+	public decorator(target: object, propertyKey: string, descriptor: PropertyDescriptor) {
+		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/src/caching/node-cache-memoize.adapter.ts

@@ -0,0 +1,47 @@
+import NodeCache from "@cacheable/node-cache";
+import type { ICache } from "./cache.js";
+
+type NodeCacheMemoizeOptions = {
+	enableMemoization: boolean;
+};
+
+/**
+ * NodeCache adapter configured for memoization (useClones: false)
+ * This allows storing object references instead of clones for true memoization
+ */
+export class NodeCacheAdapter implements ICache {
+	public static create(options: NodeCacheMemoizeOptions = { enableMemoization: false }) {
+		const nodeCache = new NodeCache({ useClones: !options.enableMemoization });
+		return new NodeCacheAdapter(nodeCache);
+	}
+	public readonly supportsMemoization = true as const;
+	private cache: NodeCache<unknown>;
+
+	public constructor(inst: NodeCache<unknown> = new NodeCache()) {
+		this.cache = inst;
+	}
+
+	public get isMemoize() {
+		return !this.cache.options.useClones;
+	}
+
+	public get(key: string): unknown {
+		return this.cache.get(key);
+	}
+
+	public set(key: string, value: unknown): void {
+		this.cache.set(key, value);
+	}
+
+	public has(key: string): boolean {
+		return this.cache.has(key);
+	}
+
+	public del(key: string): void {
+		this.cache.del(key);
+	}
+
+	public flushAll(): void {
+		this.cache.flushAll();
+	}
+}

package/src/cli/action.ts

@@ -0,0 +1,77 @@
+import type { Constructable } from "../reflection/index.js";
+import type { UnionToIntersection } from "../system/type.utils.js";
+
+export const ActionMap = Symbol("ActionMap");
+
+export type ActionClassMap = Record<string, Constructable<Action>>;
+
+export interface ResultStatus {
+	succeeded: boolean;
+	error?: string;
+}
+
+export interface Result {
+	readonly name: string;
+	readonly succeeded: boolean;
+	readonly skipped: boolean;
+	readonly message: string;
+}
+
+export class ActionResponse<TData = unknown> implements Result {
+	public static Success<TData>(name: string, data?: TData[]) {
+		return new ActionResponse<TData>({ name, data, succeeded: true });
+	}
+
+	public static Skipped(name: string) {
+		return new ActionResponse({ name, skipped: true });
+	}
+
+	public static Blocking(name: string) {
+		return new ActionResponse({ name, succeeded: true, blocking: true });
+	}
+
+	public static Error<TData = unknown>(name: string, message: string): ActionResponse<TData>;
+	public static Error<TData extends ResultStatus>(
+		name: string,
+		data: TData[],
+	): ActionResponse<TData>;
+	public static Error<TData extends ResultStatus>(
+		name: string,
+		messageOrData: string | TData[],
+		data?: TData[],
+	) {
+		if (Array.isArray(messageOrData)) {
+			const message = messageOrData
+				.filter((r) => !r.succeeded)
+				.map((r) => r.error ?? "Unknown error")
+				.join("\n");
+			return new ActionResponse<TData>({ name, message, data: messageOrData });
+		}
+		return new ActionResponse<TData>({ name, message: messageOrData, data });
+	}
+
+	public constructor(data: Partial<ActionResponse<TData>>) {
+		Object.assign(this, data);
+	}
+
+	public readonly name: string;
+	public readonly succeeded: boolean = false;
+	public readonly skipped: boolean = false;
+	public readonly blocking: boolean = false;
+	public readonly message: string;
+	public readonly data: TData[];
+}
+
+export interface Action<T extends object = object> {
+	run(options: T): Promise<ActionResponse>;
+}
+
+export type Actions = Record<string, Action>;
+
+export type ActionOptions<A extends Action> = A extends Action<infer T> ? T : never;
+
+export type MergeOptions<TActions extends Record<string, Action>> = UnionToIntersection<
+	{
+		[K in keyof TActions]: ActionOptions<TActions[K]>;
+	}[keyof TActions]
+>;

package/src/cli/command.ts

@@ -0,0 +1,173 @@
+import { Command as CommanderType, type OptionValues } from "commander";
+import type { Constructable } from "../reflection/index.js";
+import type { ActionResponse, Actions } from "./action.js";
+
+export type CommandType = Constructable<DecohereCommand>;
+
+export type CommandHandler = (opts: OptionValues, cmd: DecohereCommand) => Promise<void>;
+
+export type CommandResponse<TActions extends Actions = Actions> = {
+	[ActionName in keyof TActions]?: ActionResponse;
+};
+
+export const CommandResponse = {
+	success<T extends Actions>(
+		_ctx: unknown,
+		responses: CommandResponse<T>,
+	): CommandResponse<T> {
+		return responses;
+	},
+
+	help<T extends Actions = Actions>(): CommandResponse<T> {
+		return {} as CommandResponse<T>;
+	},
+
+	fromAction(name: string, response: ActionResponse): CommandResponse {
+		return { [name]: response };
+	},
+};
+
+/** Thrown when a command execution fails due to action errors. */
+export class CommandError extends Error {}
+
+export class DecohereCommand<TActions extends Actions = Actions> extends CommanderType {
+	public get actions(): readonly Constructable<import("./action.js").Action>[] {
+		return [];
+	}
+
+	public constructor(
+		name?: string | Constructable | Record<string, CommandType>,
+		handler?: CommandHandler,
+	) {
+		super();
+		if (typeof name === "string" || typeof name === "function") {
+			this.name(this.parseCommandName(name));
+		} else {
+			this.name(this.parseCommandName(this.constructor as unknown as Constructable));
+			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.
+	 */
+	public runsUntilStopped(_options: OptionValues): boolean {
+		return false;
+	}
+
+	public async run(
+		actions: TActions,
+		options: OptionValues,
+	): Promise<CommandResponse<TActions>> {
+		const responses = await this.runActions(actions, options);
+		this.throwOnErrors(responses);
+		return CommandResponse.success(options, responses);
+	}
+
+	public registerSubcommand(command: CommandType, onAction?: CommandHandler): void;
+	public registerSubcommand(
+		commands: Record<string, DecohereCommand | CommandType>,
+		onAction?: CommandHandler,
+	): void;
+	public registerSubcommand(
+		commands: CommandType | Record<string, DecohereCommand | CommandType>,
+		onAction?: CommandHandler,
+	): void {
+		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);
+			}
+		}
+	}
+
+	protected async runActions(
+		actions: TActions,
+		options: OptionValues,
+	): Promise<CommandResponse<TActions>> {
+		const selectedActions = this.getSelectedActions(actions);
+		const responses = {} as CommandResponse<TActions>;
+		for (const [actionKey, action] of selectedActions) {
+			responses[actionKey] = (await action.run(
+				options,
+			)) as CommandResponse<TActions>[keyof TActions];
+		}
+		return responses as CommandResponse<TActions>;
+	}
+
+	protected getSelectedActions(
+		actions: TActions,
+	): Array<[keyof TActions, TActions[keyof TActions]]> {
+		if (!this.actions.length) {
+			return [];
+		}
+
+		const actionEntries = Object.entries(actions) as Array<
+			[keyof TActions, TActions[keyof TActions]]
+		>;
+		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;
+		});
+	}
+
+	protected throwOnErrors(responses: CommandResponse<TActions>): void {
+		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")}`,
+		);
+	}
+
+	private parseCommandName(stringLike: string | Constructable) {
+		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;
+	}
+}