@buenojs/bueno 0.8.0

package/src/config/loader.ts

@@ -0,0 +1,329 @@
+/**
+ * Configuration file loader for Bueno Framework
+ * Uses Bun's native TypeScript loader to import config files
+ */
+
+import type { BuenoConfig, DeepPartial, UserConfig, UserConfigFn } from "./types";
+import { deepMerge } from "./merge";
+
+/**
+ * Configuration file search order
+ */
+const CONFIG_FILES = [
+	"bueno.config.ts",
+	"bueno.config.js",
+	".buenorc.ts",
+	".buenorc.js",
+	"bueno.config.mjs",
+];
+
+/**
+ * Loaded configuration information
+ */
+export interface LoadedConfig {
+	/** The loaded configuration */
+	config: DeepPartial<BuenoConfig>;
+	/** Path to the config file that was loaded */
+	filePath?: string;
+	/** Whether the config was loaded from cache */
+	fromCache: boolean;
+}
+
+/**
+ * Config loader cache
+ */
+const configCache = new Map<string, DeepPartial<BuenoConfig>>();
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		const file = Bun.file(path);
+		return await file.exists();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Find the first existing config file
+ */
+export async function findConfigFile(
+	cwd?: string,
+): Promise<string | undefined> {
+	const baseDir = cwd ?? process.cwd();
+
+	for (const file of CONFIG_FILES) {
+		const filePath = `${baseDir}/${file}`;
+		if (await fileExists(filePath)) {
+			return filePath;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Clear the config cache
+ */
+export function clearConfigCache(): void {
+	configCache.clear();
+}
+
+/**
+ * Get cached config
+ */
+export function getCachedConfig(path: string): DeepPartial<BuenoConfig> | undefined {
+	return configCache.get(path);
+}
+
+/**
+ * Load a configuration file
+ * Supports both default exports and named exports
+ */
+export async function loadConfigFile<T extends BuenoConfig = BuenoConfig>(
+	filePath: string,
+	options?: {
+		/** Whether to use cache */
+		useCache?: boolean;
+		/** Additional context to pass to config function */
+		context?: Record<string, unknown>;
+	},
+): Promise<LoadedConfig> {
+	const useCache = options?.useCache !== false;
+
+	// Check cache first
+	if (useCache) {
+		const cached = configCache.get(filePath);
+		if (cached) {
+			return {
+				config: cached,
+				filePath,
+				fromCache: true,
+			};
+		}
+	}
+
+	// Check if file exists
+	if (!(await fileExists(filePath))) {
+		throw new Error(`Config file not found: ${filePath}`);
+	}
+
+	try {
+		// Use Bun's native TypeScript loader
+		const module = await import(filePath);
+
+		let config: DeepPartial<T>;
+
+		// Handle different export styles
+		if (typeof module.default === "function") {
+			// Function export: export default defineConfig(() => ({ ... }))
+			config = await module.default(options?.context);
+		} else if (typeof module.default === "object" && module.default !== null) {
+			// Object export: export default { ... }
+			config = module.default;
+		} else if (module.config) {
+			// Named export: export const config = { ... }
+			config = module.config;
+		} else {
+			// Try to use the module itself as config
+			config = module;
+		}
+
+		// Cache the result
+		if (useCache) {
+			configCache.set(filePath, config as DeepPartial<BuenoConfig>);
+		}
+
+		return {
+			config: config as DeepPartial<BuenoConfig>,
+			filePath,
+			fromCache: false,
+		};
+	} catch (error) {
+		throw new Error(
+			`Failed to load config from ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+/**
+ * Load configuration from file
+ * Searches for config files in order and loads the first one found
+ */
+export async function loadConfig<T extends BuenoConfig = BuenoConfig>(
+	options?: {
+		/** Custom config file path */
+		configPath?: string;
+		/** Working directory to search for config */
+		cwd?: string;
+		/** Whether to use cache */
+		useCache?: boolean;
+		/** Additional context to pass to config function */
+		context?: Record<string, unknown>;
+	},
+): Promise<LoadedConfig> {
+	// If a specific path is provided, use it
+	if (options?.configPath) {
+		return loadConfigFile<T>(options.configPath, {
+			useCache: options.useCache,
+			context: options.context,
+		});
+	}
+
+	// Find config file
+	const filePath = await findConfigFile(options?.cwd);
+
+	if (!filePath) {
+		return {
+			config: {},
+			filePath: undefined,
+			fromCache: false,
+		};
+	}
+
+	return loadConfigFile<T>(filePath, {
+		useCache: options?.useCache,
+		context: options?.context,
+	});
+}
+
+/**
+ * Load and merge multiple config files
+ * Later files override earlier ones
+ */
+export async function loadConfigFiles(
+	filePaths: string[],
+	options?: {
+		/** Whether to use cache */
+		useCache?: boolean;
+	},
+): Promise<LoadedConfig> {
+	const configs: DeepPartial<BuenoConfig>[] = [];
+	let lastFilePath: string | undefined;
+
+	for (const filePath of filePaths) {
+		if (await fileExists(filePath)) {
+			const { config } = await loadConfigFile(filePath, options);
+			configs.push(config);
+			lastFilePath = filePath;
+		}
+	}
+
+	const mergedConfig = configs.reduce(
+		(acc, config) => deepMerge(acc, config),
+		{} as DeepPartial<BuenoConfig>,
+	);
+
+	return {
+		config: mergedConfig,
+		filePath: lastFilePath,
+		fromCache: false,
+	};
+}
+
+/**
+ * Watch a config file for changes
+ * Returns an unsubscribe function
+ */
+export function watchConfig(
+	filePath: string,
+	callback: (config: DeepPartial<BuenoConfig>) => void,
+	options?: {
+		/** Debounce time in milliseconds */
+		debounce?: number;
+	},
+): () => void {
+	let timeout: Timer | undefined;
+	const debounce = options?.debounce ?? 100;
+
+	// Use Bun's file watcher
+	const watcher = Bun.file(filePath);
+
+	// Note: Bun doesn't have a built-in file watcher API yet
+	// This is a placeholder for future implementation
+	// For now, we'll use a polling approach
+
+	const interval = setInterval(async () => {
+		try {
+			// Clear cache to force reload
+			configCache.delete(filePath);
+			const { config } = await loadConfigFile(filePath, { useCache: false });
+
+			if (timeout) {
+				clearTimeout(timeout);
+			}
+
+			timeout = setTimeout(() => {
+				callback(config);
+			}, debounce);
+		} catch {
+			// Ignore errors during watch
+		}
+	}, 1000);
+
+	return () => {
+		clearInterval(interval);
+		if (timeout) {
+			clearTimeout(timeout);
+		}
+	};
+}
+
+/**
+ * Validate that a config object has the expected structure
+ */
+export function validateConfigStructure(
+	config: unknown,
+): config is DeepPartial<BuenoConfig> {
+	if (config === null || typeof config !== "object") {
+		return false;
+	}
+
+	// Basic validation - check that all top-level keys are valid
+	const validKeys = new Set([
+		"server",
+		"database",
+		"cache",
+		"logger",
+		"health",
+		"metrics",
+		"telemetry",
+		"frontend",
+	]);
+
+	const cfg = config as Record<string, unknown>;
+	for (const key of Object.keys(cfg)) {
+		if (!validKeys.has(key)) {
+			console.warn(`Unknown config key: ${key}`);
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Extract config file path from CLI args
+ */
+export function getConfigPathFromArgs(args: string[] = process.argv): string | undefined {
+	const configIndex = args.indexOf("--config");
+	if (configIndex !== -1 && args[configIndex + 1]) {
+		return args[configIndex + 1];
+	}
+
+	// Also support -c shorthand
+	const shortIndex = args.indexOf("-c");
+	if (shortIndex !== -1 && args[shortIndex + 1]) {
+		return args[shortIndex + 1];
+	}
+
+	return undefined;
+}
+
+/**
+ * Extract config file path from environment
+ */
+export function getConfigPathFromEnv(): string | undefined {
+	return Bun.env.BUENO_CONFIG;
+}

package/src/config/merge.ts

@@ -0,0 +1,285 @@
+/**
+ * Deep merge utilities for configuration
+ */
+
+import type { BuenoConfig, DeepPartial } from "./types";
+
+/**
+ * Check if a value is a plain object (not an array, not null, not a class instance)
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (value === null || typeof value !== "object") {
+		return false;
+	}
+	const proto = Object.getPrototypeOf(value);
+	return proto === null || proto === Object.prototype;
+}
+
+/**
+ * Check if a value is an object (alias for isPlainObject)
+ */
+export function isObject(value: unknown): value is Record<string, unknown> {
+	return isPlainObject(value);
+}
+
+/**
+ * Deep merge two values
+ * - Objects are merged recursively
+ * - Arrays are concatenated (not merged element-wise)
+ * - Primitive values from source override target
+ */
+export function deepMerge<T>(target: T, source: DeepPartial<T>): T {
+	// Handle null/undefined source
+	if (source === null || source === undefined) {
+		return target;
+	}
+
+	// Handle null/undefined target
+	if (target === null || target === undefined) {
+		return source as T;
+	}
+
+	// If source is not an object, return source (override)
+	if (!isPlainObject(source)) {
+		return source as T;
+	}
+
+	// If target is not an object but source is, return source
+	if (!isPlainObject(target)) {
+		return source as T;
+	}
+
+	// Both are objects, merge them
+	const result = { ...target } as Record<string, unknown>;
+	const sourceRecord = source as Record<string, unknown>;
+	const targetRecord = target as Record<string, unknown>;
+
+	for (const key of Object.keys(source)) {
+		const sourceValue = sourceRecord[key];
+		const targetValue = targetRecord[key];
+
+		if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+			// Both are objects, merge recursively
+			result[key] = deepMerge(targetValue, sourceValue as DeepPartial<typeof targetValue>);
+		} else if (Array.isArray(sourceValue) && Array.isArray(targetValue)) {
+			// Both are arrays, concatenate them
+			result[key] = [...targetValue, ...sourceValue];
+		} else {
+			// Override with source value
+			result[key] = sourceValue;
+		}
+	}
+
+	return result as T;
+}
+
+/**
+ * Merge multiple configuration objects
+ * Later configs have higher priority
+ */
+export function mergeConfigs<T extends BuenoConfig = BuenoConfig>(
+	...configs: (DeepPartial<T> | undefined | null)[]
+): DeepPartial<T> {
+	return configs.reduce<DeepPartial<T>>((acc, config) => {
+		if (config === undefined || config === null) {
+			return acc;
+		}
+		// Use unknown as intermediate type to avoid recursive type issues
+		return deepMerge(acc as unknown as T, config as unknown as DeepPartial<T>) as unknown as DeepPartial<T>;
+	}, {} as DeepPartial<T>);
+}
+
+/**
+ * Deep clone a configuration object
+ */
+export function deepClone<T>(obj: T): T {
+	if (obj === null || typeof obj !== "object") {
+		return obj;
+	}
+
+	if (Array.isArray(obj)) {
+		return obj.map((item) => deepClone(item)) as T;
+	}
+
+	if (isPlainObject(obj)) {
+		const result: Record<string, unknown> = {};
+		for (const key of Object.keys(obj)) {
+			result[key] = deepClone(obj[key]);
+		}
+		return result as T;
+	}
+
+	// For other types (Date, Map, Set, etc.), return as-is
+	return obj;
+}
+
+/**
+ * Get a value from an object using dot notation
+ * @example getNestedValue({ a: { b: { c: 1 } } }, 'a.b.c') // returns 1
+ */
+export function getNestedValue<T = unknown>(
+	obj: Record<string, unknown>,
+	path: string,
+): T | undefined {
+	const keys = path.split(".");
+	let current: unknown = obj;
+
+	for (const key of keys) {
+		if (current === null || current === undefined) {
+			return undefined;
+		}
+		if (isPlainObject(current)) {
+			current = current[key];
+		} else {
+			return undefined;
+		}
+	}
+
+	return current as T;
+}
+
+/**
+ * Set a value in an object using dot notation
+ * @example setNestedValue({}, 'a.b.c', 1) // returns { a: { b: { c: 1 } } }
+ */
+export function setNestedValue(
+	obj: Record<string, unknown>,
+	path: string,
+	value: unknown,
+): Record<string, unknown> {
+	const keys = path.split(".");
+	const result = deepClone(obj);
+	let current: Record<string, unknown> = result;
+
+	for (let i = 0; i < keys.length - 1; i++) {
+		const key = keys[i];
+		if (!isPlainObject(current[key])) {
+			current[key] = {};
+		}
+		current = current[key] as Record<string, unknown>;
+	}
+
+	current[keys[keys.length - 1]] = value;
+	return result;
+}
+
+/**
+ * Delete a value from an object using dot notation
+ * @example deleteNestedValue({ a: { b: { c: 1 } } }, 'a.b.c') // returns { a: { b: {} } }
+ */
+export function deleteNestedValue(
+	obj: Record<string, unknown>,
+	path: string,
+): Record<string, unknown> {
+	const keys = path.split(".");
+	const result = deepClone(obj);
+	let current: Record<string, unknown> = result;
+
+	for (let i = 0; i < keys.length - 1; i++) {
+		const key = keys[i];
+		if (!isPlainObject(current[key])) {
+			return result; // Path doesn't exist, nothing to delete
+		}
+		current = current[key] as Record<string, unknown>;
+	}
+
+	delete current[keys[keys.length - 1]];
+	return result;
+}
+
+/**
+ * Check if a path exists in an object
+ */
+export function hasNestedValue(
+	obj: Record<string, unknown>,
+	path: string,
+): boolean {
+	return getNestedValue(obj, path) !== undefined;
+}
+
+/**
+ * Flatten a nested object to dot notation keys
+ * @example flattenObject({ a: { b: { c: 1 } } }) // returns { 'a.b.c': 1 }
+ */
+export function flattenObject(
+	obj: Record<string, unknown>,
+	prefix = "",
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	for (const key of Object.keys(obj)) {
+		const newKey = prefix ? `${prefix}.${key}` : key;
+		const value = obj[key];
+
+		if (isPlainObject(value)) {
+			Object.assign(result, flattenObject(value, newKey));
+		} else {
+			result[newKey] = value;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Unflatten a dot notation object to nested object
+ * @example unflattenObject({ 'a.b.c': 1 }) // returns { a: { b: { c: 1 } } }
+ */
+export function unflattenObject(
+	obj: Record<string, unknown>,
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	for (const key of Object.keys(obj)) {
+		const keys = key.split(".");
+		let current: Record<string, unknown> = result;
+
+		for (let i = 0; i < keys.length - 1; i++) {
+			const k = keys[i];
+			if (!isPlainObject(current[k])) {
+				current[k] = {};
+			}
+			current = current[k] as Record<string, unknown>;
+		}
+
+		current[keys[keys.length - 1]] = obj[key];
+	}
+
+	return result;
+}
+
+/**
+ * Compare two configurations and return the differences
+ */
+export function diffConfigs(
+	target: BuenoConfig,
+	source: BuenoConfig,
+): { added: string[]; removed: string[]; changed: string[] } {
+	const flatTarget = flattenObject(target as Record<string, unknown>);
+	const flatSource = flattenObject(source as Record<string, unknown>);
+
+	const targetKeys = new Set(Object.keys(flatTarget));
+	const sourceKeys = new Set(Object.keys(flatSource));
+
+	const added: string[] = [];
+	const removed: string[] = [];
+	const changed: string[] = [];
+
+	// Find added keys
+	for (const key of sourceKeys) {
+		if (!targetKeys.has(key)) {
+			added.push(key);
+		} else if (flatTarget[key] !== flatSource[key]) {
+			changed.push(key);
+		}
+	}
+
+	// Find removed keys
+	for (const key of targetKeys) {
+		if (!sourceKeys.has(key)) {
+			removed.push(key);
+		}
+	}
+
+	return { added, removed, changed };
+}