@gguf/coder 0.2.9 → 0.3.1

package/source/utils/logging/log-method-factory.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared factory function for creating log methods with specific levels
+ * Used across different logger implementations to reduce code duplication
+ */
+
+// Type guard to check if a logger has a specific level method
+// biome-ignore lint/suspicious/noExplicitAny: Generic logger type
+function hasLevelMethod(logger: any, level: string): boolean {
+	return logger && typeof logger[level] === 'function';
+}
+
+/**
+ * Factory function to create log method with specific level
+ * Returns overloaded function matching Logger interface
+ *
+ * @param logger - The underlying logger instance (Pino, console, etc.)
+ * @param level - The log level ('info', 'error', 'warn', etc.)
+ * @param options - Optional configuration for the log method
+ * @returns An overloaded log method that accepts both string-first and object-first signatures
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Generic logger type parameter
+export function createLogMethod<T = any>(
+	logger: T,
+	level: string,
+	options?: {
+		contextPrefix?: string;
+		consolePrefix?: string;
+		consoleMethod?: keyof Console;
+		transformArgs?: (args: unknown[], msg?: string) => unknown[];
+		// biome-ignore lint/suspicious/noExplicitAny: Generic result type
+		transformResult?: (result: any) => void;
+	},
+) {
+	const {
+		contextPrefix,
+		consolePrefix,
+		consoleMethod,
+		transformArgs,
+		transformResult,
+	} = options || {};
+
+	// Create overloaded function
+	const logMethod = (msgOrObj: string | object, ...args: unknown[]) => {
+		try {
+			// Handle console prefix fallback case
+			if (consolePrefix && consoleMethod && logger === console) {
+				// This is for fallback logger with console prefixes
+				if (typeof msgOrObj === 'object' && msgOrObj !== null) {
+					// Object first: (obj: object, msg?: string) => void
+					const obj = msgOrObj;
+					const msg = args[0] as string | undefined;
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic console method access
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic typing required
+					(console as any)[consoleMethod](`[${consolePrefix}]`, msg || '', obj);
+				} else {
+					// String first: (msg: string, ...args: unknown[]) => void
+					const msg = msgOrObj;
+					const restArgs = args.slice(1);
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic console method access
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic typing required
+					(console as any)[consoleMethod](
+						`[${consolePrefix}]`,
+						msg,
+						...restArgs,
+					);
+				}
+				return;
+			}
+
+			// Transform arguments if needed
+			const transformedArgs = transformArgs
+				? transformArgs(
+						args,
+						typeof msgOrObj === 'string' ? msgOrObj : undefined,
+					)
+				: args;
+
+			if (typeof msgOrObj === 'object' && msgOrObj !== null) {
+				// Object first: (obj: object, msg?: string) => void
+				const obj = msgOrObj as Record<string, unknown>;
+				const msg = transformedArgs[0] as string | undefined;
+
+				// Call the logger with object and optional message
+				if (hasLevelMethod(logger, level)) {
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic logger method access
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic typing required
+					const result = (logger as any)[level](msg || '', obj);
+					if (transformResult) {
+						transformResult(result);
+					}
+				}
+			} else {
+				// String first: (msg: string, ...args: unknown[]) => void
+				const msg = msgOrObj;
+
+				// Add context prefix if specified
+				const finalMsg = contextPrefix ? `[${contextPrefix}] ${msg}` : msg;
+
+				// Call the logger with message and additional args
+				if (hasLevelMethod(logger, level)) {
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic logger method access
+					// biome-ignore lint/suspicious/noExplicitAny: Dynamic typing required
+					const result = (logger as any)[level](finalMsg, ...transformedArgs);
+					if (transformResult) {
+						transformResult(result);
+					}
+				}
+			}
+		} catch (error) {
+			// Fallback to console if logger method fails
+			const fallbackLevel = level === 'trace' ? 'log' : level;
+			const consoleMethod = console[fallbackLevel as keyof Console] as (
+				// biome-ignore lint/suspicious/noExplicitAny: Variadic fallback console arguments
+				...args: any[]
+			) => void;
+			if (typeof consoleMethod === 'function') {
+				consoleMethod('Logger method failed:', {
+					level,
+					error: error instanceof Error ? error.message : String(error),
+					message: msgOrObj,
+					args,
+				});
+			}
+		}
+	};
+
+	// Return the method with both overloads
+	return logMethod as ((msg: string, ...args: unknown[]) => void) &
+		((obj: object, msg?: string) => void);
+}
+
+/**
+ * Create a set of log methods for all standard levels
+ *
+ * @param logger - The underlying logger instance
+ * @param options - Optional configuration for all log methods
+ * @returns An object containing log methods for all standard levels
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Generic logger type parameter
+export function createLogMethods<T = any>(
+	logger: T,
+	options?: {
+		contextPrefix?: string;
+		transformArgs?: (
+			args: unknown[],
+			level?: string,
+			msg?: string,
+		) => unknown[];
+		// biome-ignore lint/suspicious/noExplicitAny: Generic result type
+		transformResult?: (result: any, level?: string) => void;
+		consolePrefix?: string;
+		consoleMethod?: keyof Console;
+	},
+) {
+	const {
+		contextPrefix,
+		transformArgs,
+		transformResult,
+		consolePrefix,
+		consoleMethod,
+	} = options || {};
+
+	// Level-specific argument transformers if needed
+	const createTransformer = (level: string) => {
+		return (args: unknown[], msg?: string) => {
+			if (transformArgs) {
+				return transformArgs(args, level, msg);
+			}
+			return args;
+		};
+	};
+
+	const createResultTransformer = (level: string) => {
+		// biome-ignore lint/suspicious/noExplicitAny: Generic result type
+		return (result: any) => {
+			if (transformResult) {
+				transformResult(result, level);
+			}
+		};
+	};
+
+	return {
+		fatal: createLogMethod(logger, 'fatal', {
+			contextPrefix: contextPrefix ? 'FATAL' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('fatal'),
+			transformResult: createResultTransformer('fatal'),
+		}),
+		error: createLogMethod(logger, 'error', {
+			contextPrefix: contextPrefix ? 'ERROR' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('error'),
+			transformResult: createResultTransformer('error'),
+		}),
+		warn: createLogMethod(logger, 'warn', {
+			contextPrefix: contextPrefix ? 'WARN' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('warn'),
+			transformResult: createResultTransformer('warn'),
+		}),
+		info: createLogMethod(logger, 'info', {
+			contextPrefix: contextPrefix ? 'INFO' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('info'),
+			transformResult: createResultTransformer('info'),
+		}),
+		http: createLogMethod(logger, 'http', {
+			contextPrefix: contextPrefix ? 'HTTP' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('http'),
+			transformResult: createResultTransformer('http'),
+		}),
+		debug: createLogMethod(logger, 'debug', {
+			contextPrefix: contextPrefix ? 'DEBUG' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('debug'),
+			transformResult: createResultTransformer('debug'),
+		}),
+		trace: createLogMethod(logger, 'trace', {
+			contextPrefix: contextPrefix ? 'TRACE' : undefined,
+			consolePrefix,
+			consoleMethod,
+			transformArgs: createTransformer('trace'),
+			transformResult: createResultTransformer('trace'),
+		}),
+	};
+}

package/source/utils/logging/log-query/aggregation/aggregator.spec.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for aggregator
+ */
+
+import test from 'ava';
+import {aggregateLogEntries, getGroupKey} from './aggregator.js';
+import type {AggregationOptions, LogEntry} from '../types.js';
+
+// Helper to create test log entry
+function createLogEntry(overrides: Partial<LogEntry> = {}): LogEntry {
+	return {
+		timestamp: new Date().toISOString(),
+		level: 'info',
+		message: 'Test message',
+		...overrides,
+	};
+}
+
+test('getGroupKey: hour grouping', t => {
+	const entry = createLogEntry({timestamp: '2025-01-15T14:30:45Z'});
+
+	const key = getGroupKey(entry, 'hour');
+
+	t.is(key, '2025-01-15T14');
+});
+
+test('getGroupKey: day grouping', t => {
+	const entry = createLogEntry({timestamp: '2025-01-15T14:30:45Z'});
+
+	const key = getGroupKey(entry, 'day');
+
+	t.is(key, '2025-01-15');
+});
+
+test('getGroupKey: level grouping', t => {
+	const entry = createLogEntry({level: 'error'});
+
+	const key = getGroupKey(entry, 'level');
+
+	t.is(key, 'error');
+});
+
+test('getGroupKey: source grouping', t => {
+	const entry = createLogEntry({source: 'api-server'});
+
+	const key = getGroupKey(entry, 'source');
+
+	t.is(key, 'api-server');
+});
+
+test('getGroupKey: source grouping - missing source', t => {
+	const entry = createLogEntry({});
+
+	const key = getGroupKey(entry, 'source');
+
+	t.is(key, 'unknown');
+});
+
+test('getGroupKey: correlationId grouping', t => {
+	const entry = createLogEntry({correlationId: 'corr-123'});
+
+	const key = getGroupKey(entry, 'correlationId');
+
+	t.is(key, 'corr-123');
+});
+
+test('getGroupKey: correlationId grouping - missing', t => {
+	const entry = createLogEntry({});
+
+	const key = getGroupKey(entry, 'correlationId');
+
+	t.is(key, 'no-correlation');
+});
+
+test('getGroupKey: errorType grouping', t => {
+	const entry = createLogEntry({error: {type: 'ValidationError'}});
+
+	const key = getGroupKey(entry, 'errorType');
+
+	t.is(key, 'ValidationError');
+});
+
+test('getGroupKey: errorType grouping - missing error', t => {
+	const entry = createLogEntry({});
+
+	const key = getGroupKey(entry, 'errorType');
+
+	t.is(key, 'no-error');
+});
+
+test('aggregateLogEntries: count aggregation', t => {
+	const entries = [
+		createLogEntry({level: 'error'}),
+		createLogEntry({level: 'error'}),
+		createLogEntry({level: 'info'}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['count'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.totalGroups, 2);
+	t.is(result.groups.error?.count, 2);
+	t.is(result.groups.info?.count, 1);
+	t.truthy(result.queryTime);
+});
+
+test('aggregateLogEntries: avgDuration aggregation', t => {
+	const entries = [
+		createLogEntry({level: 'info', performance: {duration: 100}}),
+		createLogEntry({level: 'info', performance: {duration: 200}}),
+		createLogEntry({level: 'info', performance: {duration: 300}}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['avgDuration'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.groups.info?.avgDuration, 200);
+});
+
+test('aggregateLogEntries: maxDuration and minDuration', t => {
+	const entries = [
+		createLogEntry({level: 'info', performance: {duration: 100}}),
+		createLogEntry({level: 'info', performance: {duration: 500}}),
+		createLogEntry({level: 'info', performance: {duration: 200}}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['maxDuration', 'minDuration'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.groups.info?.maxDuration, 500);
+	t.is(result.groups.info?.minDuration, 100);
+});
+
+test('aggregateLogEntries: sumDuration aggregation', t => {
+	const entries = [
+		createLogEntry({level: 'info', performance: {duration: 100}}),
+		createLogEntry({level: 'info', performance: {duration: 200}}),
+		createLogEntry({level: 'info', performance: {duration: 300}}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['sumDuration'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.groups.info?.sumDuration, 600);
+});
+
+test('aggregateLogEntries: errorRate aggregation', t => {
+	const entries = [
+		createLogEntry({level: 'info', error: {message: 'Error 1'}}),
+		createLogEntry({level: 'info'}),
+		createLogEntry({level: 'info', error: {message: 'Error 2'}}),
+		createLogEntry({level: 'info'}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['errorRate'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.groups.info?.errorRate, 0.5); // 2 errors out of 4
+});
+
+test('aggregateLogEntries: memoryUsage aggregation', t => {
+	const entries = [
+		createLogEntry({
+			level: 'info',
+			performance: {memory: {heapUsed: 1000000}},
+		}),
+		createLogEntry({
+			level: 'info',
+			performance: {memory: {heapUsed: 3000000}},
+		}),
+		createLogEntry({
+			level: 'info',
+			performance: {memory: {heapUsed: 2000000}},
+		}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['memoryUsage'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.truthy(result.groups.info?.memoryUsage);
+	t.is(result.groups.info?.memoryUsage?.avgHeapUsed, 2000000);
+	t.is(result.groups.info?.memoryUsage?.maxHeapUsed, 3000000);
+	t.is(result.groups.info?.memoryUsage?.minHeapUsed, 1000000);
+});
+
+test('aggregateLogEntries: time range filter', t => {
+	const entries = [
+		createLogEntry({
+			timestamp: '2025-01-01T00:00:00Z',
+			level: 'info',
+		}),
+		createLogEntry({
+			timestamp: '2025-01-02T00:00:00Z',
+			level: 'info',
+		}),
+		createLogEntry({
+			timestamp: '2025-01-03T00:00:00Z',
+			level: 'info',
+		}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['count'],
+		timeRange: {
+			startTime: new Date('2025-01-02T00:00:00Z'),
+			endTime: new Date('2025-01-02T23:59:59Z'),
+		},
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.groups.info?.count, 1); // Only the middle entry
+});
+
+test('aggregateLogEntries: multiple groups', t => {
+	const entries = [
+		createLogEntry({level: 'error'}),
+		createLogEntry({level: 'error'}),
+		createLogEntry({level: 'warn'}),
+		createLogEntry({level: 'info'}),
+		createLogEntry({level: 'info'}),
+		createLogEntry({level: 'info'}),
+	];
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['count'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.is(result.totalGroups, 3);
+	t.is(result.groups.error?.count, 2);
+	t.is(result.groups.warn?.count, 1);
+	t.is(result.groups.info?.count, 3);
+});
+
+test('aggregateLogEntries: samples included', t => {
+	const entries = Array.from({length: 15}, (_, i) =>
+		createLogEntry({level: 'info', message: `Message ${i}`}),
+	);
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['count'],
+	};
+
+	const result = aggregateLogEntries(entries, options);
+
+	t.truthy(result.groups.info?.samples);
+	t.is(result.groups.info?.samples?.length, 10); // Max 10 samples
+});

package/source/utils/logging/log-query/aggregation/aggregator.ts

@@ -0,0 +1,159 @@
+/**
+ * Log entry aggregation engine
+ */
+
+import type {AggregationOptions, AggregationResult, LogEntry} from '../types';
+
+/**
+ * Get group key for an entry based on groupBy field
+ */
+export function getGroupKey(entry: LogEntry, groupBy: string): string {
+	switch (groupBy) {
+		case 'hour':
+			return new Date(entry.timestamp).toISOString().substring(0, 13); // YYYY-MM-DDTHH
+		case 'day':
+			return new Date(entry.timestamp).toISOString().substring(0, 10); // YYYY-MM-DD
+		case 'level':
+			return entry.level;
+		case 'source':
+			return entry.source || 'unknown';
+		case 'correlationId':
+			return entry.correlationId || 'no-correlation';
+		case 'errorType':
+			return entry.error?.type || 'no-error';
+		default:
+			return 'unknown';
+	}
+}
+
+/**
+ * Aggregate log entries based on options
+ */
+export function aggregateLogEntries(
+	entries: LogEntry[],
+	options: AggregationOptions,
+): AggregationResult {
+	const startTime = performance.now();
+
+	// Filter by time range if specified
+	let filteredEntries = entries;
+	if (options.timeRange?.startTime && options.timeRange?.endTime) {
+		filteredEntries = entries.filter(entry => {
+			const entryTime = new Date(entry.timestamp);
+			return (
+				// biome-ignore lint/style/noNonNullAssertion: timeRange existence checked in if condition above
+				entryTime >= options.timeRange!.startTime &&
+				// biome-ignore lint/style/noNonNullAssertion: timeRange existence checked in if condition above
+				entryTime <= options.timeRange!.endTime
+			);
+		});
+	}
+
+	// biome-ignore lint/suspicious/noExplicitAny: Dynamic log bindings
+	const groups: Record<string, any> = {};
+
+	// Group entries
+	for (const entry of filteredEntries) {
+		const groupKey = getGroupKey(entry, options.groupBy);
+
+		if (!groups[groupKey]) {
+			groups[groupKey] = {
+				count: 0,
+				durations: [],
+				memoryUsages: [],
+				errorCount: 0,
+				samples: [],
+			};
+		}
+
+		const group = groups[groupKey];
+		group.count++;
+
+		if (entry.performance?.duration) {
+			group.durations.push(entry.performance.duration);
+		}
+
+		if (entry.performance?.memory) {
+			group.memoryUsages.push(entry.performance.memory.heapUsed || 0);
+		}
+
+		if (entry.error) {
+			group.errorCount++;
+		}
+
+		// Keep sample entries for analysis
+		if (group.samples.length < 10) {
+			group.samples.push(entry);
+		}
+	}
+
+	// Calculate aggregations
+	// biome-ignore lint/suspicious/noExplicitAny: Dynamic log bindings
+	const result: Record<string, any> = {};
+
+	for (const [groupKey, group] of Object.entries(groups)) {
+		// biome-ignore lint/suspicious/noExplicitAny: Dynamic value type
+		const groupResult: any = {count: group.count};
+
+		if (
+			options.aggregations.includes('avgDuration') &&
+			group.durations.length > 0
+		) {
+			groupResult.avgDuration =
+				group.durations.reduce((sum: number, d: number) => sum + d, 0) /
+				group.durations.length;
+		}
+
+		if (
+			options.aggregations.includes('maxDuration') &&
+			group.durations.length > 0
+		) {
+			groupResult.maxDuration = Math.max(...group.durations);
+		}
+
+		if (
+			options.aggregations.includes('minDuration') &&
+			group.durations.length > 0
+		) {
+			groupResult.minDuration = Math.min(...group.durations);
+		}
+
+		if (options.aggregations.includes('sumDuration')) {
+			groupResult.sumDuration = group.durations.reduce(
+				(sum: number, d: number) => sum + d,
+				0,
+			);
+		}
+
+		if (options.aggregations.includes('errorRate')) {
+			groupResult.errorRate = group.errorCount / group.count;
+		}
+
+		if (
+			options.aggregations.includes('memoryUsage') &&
+			group.memoryUsages.length > 0
+		) {
+			groupResult.memoryUsage = {
+				avgHeapUsed:
+					group.memoryUsages.reduce((sum: number, m: number) => sum + m, 0) /
+					group.memoryUsages.length,
+				maxHeapUsed: Math.max(...group.memoryUsages),
+				minHeapUsed: Math.min(...group.memoryUsages),
+			};
+		}
+
+		if (options.aggregations.includes('count')) {
+			groupResult.samples = group.samples;
+		}
+
+		result[groupKey] = groupResult;
+	}
+
+	const queryTime = performance.now() - startTime;
+
+	return {
+		groups: result,
+		totalGroups: Object.keys(result).length,
+		queryTime,
+	};
+}