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

package/src/cli/index.ts

@@ -0,0 +1,30 @@
+export type {
+	Action,
+	ActionClassMap,
+	ActionOptions,
+	Actions,
+	MergeOptions,
+	Result,
+	ResultStatus,
+} from "./action.js";
+export { ActionMap, ActionResponse } from "./action.js";
+export type { CommandHandler, CommandType } from "./command.js";
+export { CommandError, CommandResponse, DecohereCommand } from "./command.js";
+export type {
+	ApplicationModule,
+	CommandMap as CommandClassMap,
+	ModuleConfig,
+	WorkspaceFactoryOptions,
+} from "./module.type.js";
+export { ModuleManifest } from "./module.type.js";
+export {
+	ConfigFileOption,
+	ConfigurationOption,
+	DryRunOption,
+	EnvFileIfExistsOption,
+	EnvFileOption,
+	LogLevelOption,
+	NoBuildOptions,
+	NoCleanOptions,
+	ProjectOption,
+} from "./options.js";

package/src/cli/module.type.ts

@@ -0,0 +1,48 @@
+import type { ContainerBuilder } from "../composition/index.js";
+import type { ActionClassMap } from "./action.js";
+import type { CommandType, DecohereCommand } from "./command.js";
+
+export type CommandMap = Record<string, CommandType>;
+
+export type WorkspaceFactoryOptions = {
+	configFile?: string;
+	rootDir?: string;
+};
+
+export interface ApplicationModule {
+	id: string;
+	dispose?(): void;
+	asyncDispose?(): Promise<void>;
+	command: DecohereCommand;
+}
+
+export type ModuleConfig = {
+	actions?: ActionClassMap;
+	commands?: CommandMap;
+};
+
+/**
+ * Simple declaration interface for a CLI module.
+ * Extend this and implement the four abstract members.
+ */
+export abstract class ModuleManifest {
+	/** Unique module identifier, used as the root command name. */
+	public abstract readonly id: string;
+
+	/** Sub-command classes this module contributes. */
+	public readonly commands: CommandMap = {};
+
+	/** Action classes this module contributes. */
+	public readonly actions: ActionClassMap = {};
+
+	/** The root command class for this module. */
+	public abstract readonly command: CommandType;
+
+	/** Register infrastructure services into the DI container. */
+	public registerServices(_builder: ContainerBuilder): void {}
+
+	/** Lazily create a workspace instance. Return null if this module does not use a workspace. */
+	public createWorkspace(_options: WorkspaceFactoryOptions): Promise<object | null> {
+		return Promise.resolve(null);
+	}
+}

package/src/cli/options.ts

@@ -0,0 +1,81 @@
+import { Option } from "commander";
+
+function parseOptionalBoolean(input: string | boolean): boolean {
+	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 {
+	public constructor(defaultValue: string) {
+		super("--configuration <configuration>", "Configuration name");
+		this.default(defaultValue);
+	}
+}
+
+export class ConfigFileOption extends Option {
+	public constructor(defaultValue = ".decohere.js") {
+		super("--config-file <file>", "Path to Decohere config file");
+		this.default(defaultValue);
+	}
+}
+
+export class LogLevelOption extends Option {
+	public constructor() {
+		super("--log-level <level>", "Log level (trace, debug, info, warn, error)");
+	}
+}
+
+export class EnvFileOption extends Option {
+	public constructor() {
+		super("--env-file <file>", "Load environment variables from this file before running");
+	}
+}
+
+export class EnvFileIfExistsOption extends Option {
+	public constructor() {
+		super(
+			"--env-file-if-exists <file>",
+			"Like --env-file, but skip it when the file is missing",
+		);
+	}
+}
+
+export class NoCleanOptions extends Option {
+	public constructor(defaultValue: boolean) {
+		super("--no-clean", "Will not clean the project directories");
+		this.default(defaultValue);
+	}
+}
+
+export class NoBuildOptions extends Option {
+	public constructor(defaultValue: boolean) {
+		super("--no-build", "Will not run the build step");
+		this.default(defaultValue);
+	}
+}
+
+export class DryRunOption extends Option {
+	public constructor(description: string, defaultValue = false) {
+		super("--dry-run [dryRun]", description);
+		this.default(defaultValue);
+		this.preset(true);
+		this.argParser(parseOptionalBoolean);
+	}
+}
+
+export class ProjectOption extends Option {
+	public constructor() {
+		super("--project <project>", "Project name to target");
+	}
+}

package/src/collections/find-duplicates.ts

@@ -0,0 +1,16 @@
+export function findDuplicatesByKey<T>(items: T[], key: keyof T): [string, T[]][] {
+	return findDuplicatesBy(items, (item) => String(item[key]));
+}
+
+export function findDuplicatesBy<T>(
+	items: T[],
+	selector: (item: T) => string,
+): [string, T[]][] {
+	const groups = new Map<string, T[]>();
+	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/src/collections/merge-arrays.ts

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

package/src/collections/sum.ts

@@ -0,0 +1,71 @@
+export function sumByKey<T>(objects: T[], key: keyof T): number;
+export function sumByKey<T>(objects: T[], key: keyof T): bigint;
+export function sumByKey<T>(objects: T[], key: keyof T): number | bigint {
+	return sum(objects, key);
+}
+
+export function sumBy<T>(objects: T[], key: (obj: T) => number): number;
+export function sumBy<T>(objects: T[], key: (obj: T) => bigint): bigint;
+export function sumBy<T>(objects: T[], key: (obj: T) => number | bigint): number | bigint {
+	return sum(objects, key);
+}
+
+function extractValueFromItem<T>(
+	item: T,
+	key: keyof T | ((obj: T) => number | bigint),
+): number | bigint {
+	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: unknown): value is number | bigint {
+	return typeof value === "number" || typeof value === "bigint";
+}
+
+function determineSumType(firstValue: number | bigint): "bigint" | "number" {
+	return typeof firstValue === "bigint" ? "bigint" : "number";
+}
+
+function getInitialSumValue(sumType: "bigint" | "number"): number | bigint {
+	return sumType === "bigint" ? 0n : 0;
+}
+
+function addValues(
+	total: number | bigint,
+	value: number | bigint,
+	sumType: "bigint" | "number",
+): number | bigint {
+	if (sumType === "bigint") {
+		const totalBigInt = total as bigint;
+		const valueBigInt = typeof value === "bigint" ? value : BigInt(value);
+		return totalBigInt + valueBigInt;
+	}
+
+	const totalNumber = total as number;
+	const valueNumber = typeof value === "number" ? value : Number(value);
+	return totalNumber + valueNumber;
+}
+
+function sum<T>(objects: T[], key: (obj: T) => number): number;
+function sum<T>(objects: T[], key: (obj: T) => bigint): bigint;
+function sum<T>(objects: T[], key: (obj: T) => number | bigint): number | bigint;
+function sum<T>(objects: T[], key: keyof T): number | bigint;
+function sum<T>(objects: T[], key: keyof T | ((obj: T) => number | bigint)): number | bigint {
+	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/src/collections/unique-objects.ts

@@ -0,0 +1,23 @@
+export function uniqueObjectsByKey<T>(objects: T[], key: keyof T): T[] {
+	return uniqueObjects(objects, key);
+}
+
+export function uniqueObjectsBy<T>(objects: T[], key: (obj: T) => string): T[] {
+	return uniqueObjects(objects, key);
+}
+
+function uniqueObjects<T>(objects: T[], key: (obj: T) => string);
+function uniqueObjects<T>(objects: T[], key: keyof T);
+function uniqueObjects<T>(objects: T[], key: keyof T | ((obj: T) => string)) {
+	const getKey = (key: keyof T | ((obj: T) => string), item: T) => {
+		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/src/composition/index.ts

@@ -0,0 +1,48 @@
+import type { Constructable } from "../reflection/index.js";
+
+export type ResolveRequest<T extends object = object> = string | symbol | Constructable<T>;
+
+export type Scope = "single-instance" | "request" | "transient";
+
+export interface ServiceProvider {
+	/**
+	 * @param key
+	 * @throws {ServiceNotFoundException}
+	 */
+	resolve<T extends object>(key: ResolveRequest<T>): T;
+
+	resolveMany<T extends object = object>(resolveRequest: ResolveRequest<T>): T[];
+}
+
+export interface LifetimeScope extends ServiceProvider {
+	/** A name must be unique among open scopes; omit it for per-request scopes. */
+	beginScope(name?: string): LifetimeScope;
+	[Symbol.dispose](): void;
+	[Symbol.asyncDispose](): Promise<void>;
+}
+
+export interface IContainer extends LifetimeScope {}
+
+export interface ContainerRegistrar {
+	registerTransient(key: string | symbol, type: Constructable): unknown;
+	registerTransient(type: Constructable): unknown;
+
+	registerRequestScoped<T>(type: () => T): unknown;
+	registerRequestScoped<T>(key: string | symbol, type: () => T): unknown;
+	registerRequestScoped(key: string | symbol, type: Constructable): unknown;
+	registerRequestScoped(type: Constructable): unknown;
+
+	registerSingleton(key: string | symbol | Constructable, instance: object): unknown;
+	registerSingleton(key: string | symbol, type: Constructable): unknown;
+	registerSingleton(type: Constructable): unknown;
+
+	registerType(type: Constructable, scope?: Scope): unknown;
+
+	registerTypes(...types: Constructable[]): unknown[];
+	registerTypes(scope: Scope, ...types: Constructable[]): unknown[];
+}
+
+export interface ContainerBuilder extends ContainerRegistrar {
+	readonly override: ContainerRegistrar;
+	build(): IContainer;
+}

package/src/configuration/configuration.types.ts

@@ -0,0 +1,13 @@
+import type { Constructable } from "../reflection/index.js";
+
+export const ConfigurationServiceToken = Symbol("IConfigurationService");
+
+export interface IConfigurationService {
+	readonly dataSources: readonly IConfigurationDataSource[];
+	get<T extends object>(typeOrString: Constructable<T> | string): Promise<T>;
+}
+
+export interface IConfigurationDataSource {
+	readonly name: string;
+	getData(): Promise<Record<string, unknown>>;
+}

package/src/diagnostics/index.ts

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

package/src/diagnostics/trace.ts

@@ -0,0 +1,97 @@
+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" } });
+	}
+}
+
+type AnyFn = (...args: unknown[]) => unknown;
+type TimingLevel = "info" | "trace";
+
+function serializeArgs(args: unknown[]): string {
+	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: AnyFn,
+	className: string,
+	methodName: string,
+	logLevel: TimingLevel,
+): AnyFn {
+	let logger: ReturnType<typeof scribe.logger> | undefined;
+	return function (this: unknown, ...args: unknown[]) {
+		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: object,
+	propertyKey: string,
+	descriptor: PropertyDescriptor,
+): PropertyDescriptor {
+	if (!isTraceEnabled) return descriptor;
+	const className = (target as { constructor: { name: string } }).constructor.name;
+	descriptor.value = wrapWithTiming(
+		descriptor.value as AnyFn,
+		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: object,
+	propertyKey: string,
+	descriptor: PropertyDescriptor,
+): PropertyDescriptor {
+	const className = (target as { constructor: { name: string } }).constructor.name;
+	descriptor.value = wrapWithTiming(descriptor.value as AnyFn, className, propertyKey, "info");
+	return descriptor;
+}
+
+export function Trace(constructor: { name: string; prototype: object }): void {
+	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 as AnyFn, className, key, "trace");
+		Object.defineProperty(constructor.prototype, key, descriptor);
+	}
+}

package/{es6/src/extensibility/decorator-factory-base.js → src/extensibility/decorator-factory-base.ts}

@@ -1,3 +1,5 @@
+import type { FunctionDecorator } from "./decorator-factory.js";
+
 /**
  * Base class for creating decorator factory instances with methods that can be
  * conditionally disabled during unit testing.
@@ -25,15 +27,21 @@
  *   }
  * }
  * ```
- */ export class DecoratorFactoryBase {
-    /**
+ */
+
+export abstract class DecoratorFactoryBase {
+	/**
 	 * Utility method to check if we're currently in a test environment
-	 */ isTestEnvironment() {
-        return process.env.TEST === "true";
-    }
-    /**
+	 */
+	protected isTestEnvironment(): boolean {
+		return process.env.TEST === "true";
+	}
+
+	/**
 	 * Creates a no-op decorator that returns the original function unchanged
-	 */ createNoOpDecorator() {
-        return (_target, _propertyKey, descriptor)=>descriptor;
-    }
+	 */
+	protected createNoOpDecorator(): FunctionDecorator {
+		return (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) =>
+			descriptor;
+	}
 }

package/src/extensibility/decorator-factory.ts

@@ -0,0 +1,44 @@
+/**
+ * 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: object,
+	_propertyKey: string,
+	descriptor: PropertyDescriptor,
+) {
+	const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+
+	descriptor.value = function (this: unknown, ...args: unknown[]) {
+		// 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: unknown) => originalFunction;
+		}
+		// Otherwise, apply the original decorator method
+		return originalMethod.apply(this, args);
+	};
+
+	return descriptor;
+}
+
+/**
+ * Type definition for a function decorator
+ */
+export type FunctionDecorator = (
+	target: object,
+	propertyKey: string,
+	descriptor: PropertyDescriptor,
+) => PropertyDescriptor | undefined;
+
+/**
+ * Type definition for a decorator factory function (returns a decorator)
+ */
+export type DecoratorFactory<TOptions = unknown> = (options?: TOptions) => FunctionDecorator;

package/src/extensibility/extension.ts

@@ -0,0 +1,34 @@
+import type { Type } from "../reflection/types/reflection.types.js";
+
+export type ExtensionOptions = {
+	/**
+	 * Also install the method on the constructor. Use for singleton facades
+	 * (`scribe.withPinoPretty()`) whose instance lives at `ctor.instance`.
+	 */
+	static?: boolean;
+};
+
+export function extension(ctor: Type, options?: ExtensionOptions) {
+	return (_target: object, propertyKey: string, descriptor: PropertyDescriptor) => {
+		const originalFunction = descriptor.value as (...args: unknown[]) => unknown;
+
+		ctor.prototype[propertyKey] = function (...args: unknown[]) {
+			return originalFunction.apply(this, [this, ...args]);
+		};
+
+		if (options?.static) {
+			Object.defineProperty(ctor, propertyKey, {
+				configurable: true,
+				writable: true,
+				value(...args: unknown[]) {
+					const receiver = singletonOf(ctor) ?? this;
+					return originalFunction.apply(receiver, [receiver, ...args]);
+				},
+			});
+		}
+	};
+}
+
+function singletonOf(ctor: Type): unknown {
+	return (ctor as { instance?: unknown }).instance;
+}

package/src/extensibility/mixwith.ts

@@ -0,0 +1,42 @@
+type Constructor<T = object> = abstract new (...args: unknown[]) => T;
+
+type UnionToIntersection<T> = (T extends unknown ? (arg: T) => void : never) extends (
+	arg: infer TResult,
+) => void
+	? TResult
+	: never;
+
+type MixedInstance<TMixins extends readonly Constructor[]> = UnionToIntersection<
+	InstanceType<TMixins[number]>
+>;
+
+type MixedClass<TMixins extends readonly Constructor[]> = abstract new (
+	...args: unknown[]
+) => MixedInstance<TMixins>;
+
+const BLOCKED_PROTOTYPE_KEYS = new Set(["constructor", "prototype", "name", "length"]);
+
+function copyPrototypeProperties(target: object, source: object) {
+	for (const key of Reflect.ownKeys(source)) {
+		if (typeof key === "string" && BLOCKED_PROTOTYPE_KEYS.has(key)) {
+			continue;
+		}
+
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null) {
+			continue;
+		}
+
+		Object.defineProperty(target, key, descriptor);
+	}
+}
+
+export function mixwith<TMixins extends readonly Constructor[]>(...mixins: TMixins) {
+	abstract class Mixed {}
+
+	for (const mixin of mixins) {
+		copyPrototypeProperties(Mixed.prototype, mixin.prototype);
+	}
+
+	return Mixed as MixedClass<TMixins>;
+}

package/src/extensibility/pipeline.ts

@@ -0,0 +1,60 @@
+import { scribe } from "@decohere/scribe";
+
+export interface PipelineStep<
+	TContext extends Record<string, unknown> = Record<string, unknown>,
+> {
+	run(ctx: TContext, next: Next): Promise<void> | void;
+}
+
+export type Next = () => Promise<void> | void;
+export class Pipeline<T extends Record<string, unknown>> {
+	private readonly stack: [string, PipelineStep<T>, ((ctx: T) => boolean)?][];
+	private readonly logger = scribe.logger(Pipeline.name);
+	private currentStep: string | undefined;
+	public constructor(...steps: [string, PipelineStep<T>, ((ctx: T) => boolean)?][]) {
+		this.stack = steps;
+	}
+
+	public [Symbol.dispose]() {
+		for (const [, step] of this.stack) {
+			if (Symbol.dispose in step) {
+				(step as Disposable)[Symbol.dispose]();
+			}
+		}
+	}
+
+	public async start(context: T) {
+		const runStep = async (index: number): Promise<void> => {
+			const [key, middleware, when] = this.stack[index] ?? [];
+			if (middleware == null) {
+				return;
+			}
+
+			if (when != null && !when(context)) {
+				this.logger.info(`Skipping step ${key}`);
+				return await runStep(index + 1);
+			}
+
+			this.currentStep = key;
+			this.logger.info(`Running step ${key}`);
+			await middleware.run(context, async () => {
+				await runStep(index + 1);
+			});
+		};
+
+		try {
+			await runStep(0);
+		} catch (error) {
+			const step = this.currentStep ?? "unknown";
+			if (error instanceof Error) {
+				throw new Error(`Pipeline step '${step}' failed: ${error.message}`, {
+					cause: error,
+				});
+			}
+
+			throw new Error(`Pipeline step '${step}' failed with non-Error value`, {
+				cause: error,
+			});
+		}
+	}
+}