@gguf/coder 0.2.9 → 0.3.1

package/source/utils/logging/log-query/storage/circular-buffer.spec.ts

@@ -0,0 +1,143 @@
+/**
+ * Tests for circular buffer
+ */
+
+import test from 'ava';
+import {CircularBuffer} from './circular-buffer.js';
+import type {LogEntry} from '../types.js';
+
+// Helper to create a test log entry
+function createLogEntry(id: number): LogEntry {
+	return {
+		timestamp: new Date(Date.now() + id * 1000).toISOString(),
+		level: 'info',
+		message: `Test message ${id}`,
+	};
+}
+
+test('CircularBuffer: constructor creates empty buffer', t => {
+	const buffer = new CircularBuffer(10);
+	t.is(buffer.getCount(), 0);
+	t.deepEqual(buffer.getAll(), []);
+});
+
+test('CircularBuffer: add single entry', t => {
+	const buffer = new CircularBuffer(10);
+	const entry = createLogEntry(1);
+
+	const removed = buffer.add(entry);
+
+	t.is(removed, undefined, 'Should not remove entry when buffer not full');
+	t.is(buffer.getCount(), 1);
+	t.deepEqual(buffer.getAll(), [entry]);
+});
+
+test('CircularBuffer: add multiple entries within capacity', t => {
+	const buffer = new CircularBuffer(10);
+	const entries = [createLogEntry(1), createLogEntry(2), createLogEntry(3)];
+
+	for (const entry of entries) {
+		buffer.add(entry);
+	}
+
+	t.is(buffer.getCount(), 3);
+	t.deepEqual(buffer.getAll(), entries);
+});
+
+test('CircularBuffer: add entries beyond capacity (wraparound)', t => {
+	const buffer = new CircularBuffer(3);
+	const entries = [
+		createLogEntry(1),
+		createLogEntry(2),
+		createLogEntry(3),
+		createLogEntry(4),
+	];
+
+	buffer.add(entries[0]);
+	buffer.add(entries[1]);
+	buffer.add(entries[2]);
+
+	// Adding 4th entry should remove first entry
+	const removed = buffer.add(entries[3]);
+
+	t.deepEqual(removed, entries[0], 'Should remove oldest entry');
+	t.is(buffer.getCount(), 3, 'Count should stay at max capacity');
+	t.deepEqual(buffer.getAll(), [entries[1], entries[2], entries[3]]);
+});
+
+test('CircularBuffer: wraparound maintains order', t => {
+	const buffer = new CircularBuffer(3);
+
+	// Fill buffer
+	buffer.add(createLogEntry(1));
+	buffer.add(createLogEntry(2));
+	buffer.add(createLogEntry(3));
+
+	// Add more to cause wraparound
+	buffer.add(createLogEntry(4));
+	buffer.add(createLogEntry(5));
+
+	const all = buffer.getAll();
+	t.is(all.length, 3);
+	t.is(all[0]?.message, 'Test message 3');
+	t.is(all[1]?.message, 'Test message 4');
+	t.is(all[2]?.message, 'Test message 5');
+});
+
+test('CircularBuffer: clear resets buffer', t => {
+	const buffer = new CircularBuffer(10);
+
+	buffer.add(createLogEntry(1));
+	buffer.add(createLogEntry(2));
+	buffer.add(createLogEntry(3));
+
+	t.is(buffer.getCount(), 3);
+
+	buffer.clear();
+
+	t.is(buffer.getCount(), 0);
+	t.deepEqual(buffer.getAll(), []);
+});
+
+test('CircularBuffer: clear allows reuse', t => {
+	const buffer = new CircularBuffer(3);
+
+	buffer.add(createLogEntry(1));
+	buffer.add(createLogEntry(2));
+	buffer.clear();
+
+	const entry = createLogEntry(3);
+	buffer.add(entry);
+
+	t.is(buffer.getCount(), 1);
+	t.deepEqual(buffer.getAll(), [entry]);
+});
+
+test('CircularBuffer: getAll returns entries in order (oldest to newest)', t => {
+	const buffer = new CircularBuffer(5);
+
+	for (let i = 1; i <= 5; i++) {
+		buffer.add(createLogEntry(i));
+	}
+
+	const all = buffer.getAll();
+	t.is(all.length, 5);
+
+	for (let i = 0; i < 5; i++) {
+		t.is(all[i]?.message, `Test message ${i + 1}`);
+	}
+});
+
+test('CircularBuffer: handles single entry capacity', t => {
+	const buffer = new CircularBuffer(1);
+
+	const entry1 = createLogEntry(1);
+	const entry2 = createLogEntry(2);
+
+	buffer.add(entry1);
+	t.deepEqual(buffer.getAll(), [entry1]);
+
+	const removed = buffer.add(entry2);
+	t.deepEqual(removed, entry1);
+	t.deepEqual(buffer.getAll(), [entry2]);
+});

package/source/utils/logging/log-query/storage/circular-buffer.ts

@@ -0,0 +1,75 @@
+/**
+ * Circular buffer implementation for efficient log storage
+ */
+
+import type {LogEntry} from '../types';
+
+/**
+ * Circular buffer for storing log entries with O(1) add/remove
+ */
+export class CircularBuffer {
+	private entries: (LogEntry | undefined)[];
+	private head: number = 0; // Index of oldest entry
+	private tail: number = 0; // Index where next entry goes
+	private count: number = 0; // Current number of entries
+	private maxEntries: number;
+
+	constructor(maxEntries: number) {
+		this.maxEntries = maxEntries;
+		this.entries = new Array(maxEntries); // Pre-allocate array
+	}
+
+	/**
+	 * Add entry to buffer - O(1) operation
+	 * Returns the removed entry if buffer was full, undefined otherwise
+	 */
+	add(entry: LogEntry): LogEntry | undefined {
+		let removed: LogEntry | undefined;
+
+		// If buffer is full, remove oldest entry
+		if (this.count === this.maxEntries) {
+			removed = this.entries[this.head];
+			// Advance head (oldest entry pointer)
+			this.head = (this.head + 1) % this.maxEntries;
+		} else {
+			this.count++;
+		}
+
+		// Write new entry at tail position - O(1)
+		this.entries[this.tail] = entry;
+		this.tail = (this.tail + 1) % this.maxEntries;
+
+		return removed;
+	}
+
+	/**
+	 * Get all entries as array (oldest to newest)
+	 */
+	getAll(): LogEntry[] {
+		const result: LogEntry[] = [];
+		for (let i = 0; i < this.count; i++) {
+			const entry = this.entries[(this.head + i) % this.maxEntries];
+			if (entry) {
+				result.push(entry);
+			}
+		}
+		return result;
+	}
+
+	/**
+	 * Get current count of entries
+	 */
+	getCount(): number {
+		return this.count;
+	}
+
+	/**
+	 * Clear all entries
+	 */
+	clear(): void {
+		this.entries = new Array(this.maxEntries);
+		this.head = 0;
+		this.tail = 0;
+		this.count = 0;
+	}
+}

package/source/utils/logging/log-query/storage/index-manager.spec.ts

@@ -0,0 +1,150 @@
+/**
+ * Tests for index manager
+ */
+
+import test from 'ava';
+import {IndexManager} from './index-manager.js';
+import type {LogEntry} from '../types.js';
+
+// Helper to create test log entry
+function createLogEntry(
+	level: string,
+	correlationId?: string,
+	source?: string,
+): LogEntry {
+	return {
+		timestamp: new Date().toISOString(),
+		level,
+		message: 'Test message',
+		correlationId,
+		source,
+	};
+}
+
+test('IndexManager: starts with empty indexes', t => {
+	const manager = new IndexManager();
+
+	t.is(manager.getIndexValues('level'), undefined);
+	t.is(manager.getIndexValues('correlationId'), undefined);
+	t.is(manager.getIndexValues('source'), undefined);
+});
+
+test('IndexManager: adds level index', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('error');
+
+	manager.updateIndexes(entry, true);
+
+	const levelIndex = manager.getIndexValues('level');
+	t.truthy(levelIndex);
+	t.true(levelIndex?.has('error'));
+});
+
+test('IndexManager: adds correlation ID index', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('info', 'corr-123');
+
+	manager.updateIndexes(entry, true);
+
+	const corrIndex = manager.getIndexValues('correlationId');
+	t.truthy(corrIndex);
+	t.true(corrIndex?.has('corr-123'));
+});
+
+test('IndexManager: adds source index', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('info', undefined, 'api-server');
+
+	manager.updateIndexes(entry, true);
+
+	const sourceIndex = manager.getIndexValues('source');
+	t.truthy(sourceIndex);
+	t.true(sourceIndex?.has('api-server'));
+});
+
+test('IndexManager: adds multiple entries to same index', t => {
+	const manager = new IndexManager();
+
+	manager.updateIndexes(createLogEntry('error'), true);
+	manager.updateIndexes(createLogEntry('warn'), true);
+	manager.updateIndexes(createLogEntry('info'), true);
+
+	const levelIndex = manager.getIndexValues('level');
+	t.is(levelIndex?.size, 3);
+	t.true(levelIndex?.has('error'));
+	t.true(levelIndex?.has('warn'));
+	t.true(levelIndex?.has('info'));
+});
+
+test('IndexManager: removes from level index', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('error');
+
+	manager.updateIndexes(entry, true);
+	t.true(manager.getIndexValues('level')?.has('error'));
+
+	manager.updateIndexes(entry, false);
+	t.false(manager.getIndexValues('level')?.has('error'));
+});
+
+test('IndexManager: removes from correlation ID index', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('info', 'corr-123');
+
+	manager.updateIndexes(entry, true);
+	t.true(manager.getIndexValues('correlationId')?.has('corr-123'));
+
+	manager.updateIndexes(entry, false);
+	t.false(manager.getIndexValues('correlationId')?.has('corr-123'));
+});
+
+test('IndexManager: removes from source index', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('info', undefined, 'api-server');
+
+	manager.updateIndexes(entry, true);
+	t.true(manager.getIndexValues('source')?.has('api-server'));
+
+	manager.updateIndexes(entry, false);
+	t.false(manager.getIndexValues('source')?.has('api-server'));
+});
+
+test('IndexManager: clear removes all indexes', t => {
+	const manager = new IndexManager();
+
+	manager.updateIndexes(createLogEntry('error', 'corr-1', 'api'), true);
+	manager.updateIndexes(createLogEntry('warn', 'corr-2', 'db'), true);
+
+	t.truthy(manager.getIndexValues('level'));
+	t.truthy(manager.getIndexValues('correlationId'));
+	t.truthy(manager.getIndexValues('source'));
+
+	manager.clear();
+
+	t.is(manager.getIndexValues('level'), undefined);
+	t.is(manager.getIndexValues('correlationId'), undefined);
+	t.is(manager.getIndexValues('source'), undefined);
+});
+
+test('IndexManager: handles entries without optional fields', t => {
+	const manager = new IndexManager();
+	const entry = createLogEntry('info'); // No correlationId or source
+
+	manager.updateIndexes(entry, true);
+
+	t.truthy(manager.getIndexValues('level'));
+	t.is(manager.getIndexValues('correlationId'), undefined);
+	t.is(manager.getIndexValues('source'), undefined);
+});
+
+test('IndexManager: handles duplicate values correctly', t => {
+	const manager = new IndexManager();
+
+	manager.updateIndexes(createLogEntry('error'), true);
+	manager.updateIndexes(createLogEntry('error'), true);
+	manager.updateIndexes(createLogEntry('error'), true);
+
+	const levelIndex = manager.getIndexValues('level');
+	t.is(levelIndex?.size, 1); // Set should only have one 'error' entry
+	t.true(levelIndex?.has('error'));
+});

package/source/utils/logging/log-query/storage/index-manager.ts

@@ -0,0 +1,71 @@
+/**
+ * Index manager for efficient log entry lookups
+ */
+
+import type {LogEntry} from '../types';
+
+/**
+ * Manages indexes for log entries
+ */
+export class IndexManager {
+	private indexes: Map<string, Set<string>> = new Map();
+
+	/**
+	 * Update indexes when entry is added or removed
+	 */
+	updateIndexes(entry: LogEntry, add: boolean): void {
+		// Update correlation ID index
+		if (entry.correlationId) {
+			if (!this.indexes.has('correlationId')) {
+				this.indexes.set('correlationId', new Set());
+			}
+			// biome-ignore lint/style/noNonNullAssertion: Index exists after set above
+			const index = this.indexes.get('correlationId')!;
+			if (add) {
+				index.add(entry.correlationId);
+			} else {
+				index.delete(entry.correlationId);
+			}
+		}
+
+		// Update source index
+		if (entry.source) {
+			if (!this.indexes.has('source')) {
+				this.indexes.set('source', new Set());
+			}
+			// biome-ignore lint/style/noNonNullAssertion: Index exists after set above
+			const index = this.indexes.get('source')!;
+			if (add) {
+				index.add(entry.source);
+			} else {
+				index.delete(entry.source);
+			}
+		}
+
+		// Update level index
+		if (!this.indexes.has('level')) {
+			this.indexes.set('level', new Set());
+		}
+		// biome-ignore lint/style/noNonNullAssertion: Index exists after set above
+		const levelIndex = this.indexes.get('level')!;
+		if (add) {
+			levelIndex.add(entry.level);
+		} else {
+			levelIndex.delete(entry.level);
+		}
+	}
+
+	/**
+	 * Clear all indexes
+	 */
+	clear(): void {
+		this.indexes.clear();
+	}
+
+	/**
+	 * Get all values for a specific index
+	 */
+	getIndexValues(indexName: string): Set<string> | undefined {
+		return this.indexes.get(indexName);
+	}
+}

package/source/utils/logging/log-query/storage/log-storage.spec.ts

@@ -0,0 +1,257 @@
+/**
+ * Tests for log storage
+ */
+
+import test from 'ava';
+import {LogStorage} from './log-storage.js';
+import type {AggregationOptions, LogEntry, LogQuery} 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('LogStorage: constructor creates empty storage', t => {
+	const storage = new LogStorage(10);
+
+	t.is(storage.getEntryCount(), 0);
+});
+
+test('LogStorage: addEntry adds entry to storage', t => {
+	const storage = new LogStorage(10);
+	const entry = createLogEntry();
+
+	storage.addEntry(entry);
+
+	t.is(storage.getEntryCount(), 1);
+});
+
+test('LogStorage: addEntry multiple entries', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry({message: '1'}));
+	storage.addEntry(createLogEntry({message: '2'}));
+	storage.addEntry(createLogEntry({message: '3'}));
+
+	t.is(storage.getEntryCount(), 3);
+});
+
+test('LogStorage: addEntry respects max capacity', t => {
+	const storage = new LogStorage(3);
+
+	storage.addEntry(createLogEntry({message: '1'}));
+	storage.addEntry(createLogEntry({message: '2'}));
+	storage.addEntry(createLogEntry({message: '3'}));
+	storage.addEntry(createLogEntry({message: '4'}));
+
+	t.is(storage.getEntryCount(), 3); // Should stay at max
+});
+
+test('LogStorage: query returns all entries', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry({level: 'error'}));
+	storage.addEntry(createLogEntry({level: 'info'}));
+	storage.addEntry(createLogEntry({level: 'warn'}));
+
+	const query: LogQuery = {};
+	const result = storage.query(query);
+
+	t.is(result.entries.length, 3);
+	t.is(result.totalCount, 3);
+});
+
+test('LogStorage: query filters by level', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry({level: 'error'}));
+	storage.addEntry(createLogEntry({level: 'info'}));
+	storage.addEntry(createLogEntry({level: 'error'}));
+
+	const query: LogQuery = {levels: ['error']};
+	const result = storage.query(query);
+
+	t.is(result.entries.length, 2);
+	t.is(result.filteredCount, 2);
+	t.is(result.totalCount, 3);
+});
+
+test('LogStorage: query applies pagination', t => {
+	const storage = new LogStorage(100);
+
+	for (let i = 0; i < 10; i++) {
+		storage.addEntry(createLogEntry({message: `Entry ${i}`}));
+	}
+
+	const query: LogQuery = {limit: 3, offset: 2};
+	const result = storage.query(query);
+
+	t.is(result.entries.length, 3);
+	t.is(result.filteredCount, 10);
+	t.true(result.hasMore);
+});
+
+test('LogStorage: query sorts entries', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry({timestamp: '2025-01-03T00:00:00Z'}));
+	storage.addEntry(createLogEntry({timestamp: '2025-01-01T00:00:00Z'}));
+	storage.addEntry(createLogEntry({timestamp: '2025-01-02T00:00:00Z'}));
+
+	const query: LogQuery = {sortBy: 'timestamp', sortOrder: 'asc'};
+	const result = storage.query(query);
+
+	t.is(result.entries[0]?.timestamp, '2025-01-01T00:00:00Z');
+	t.is(result.entries[1]?.timestamp, '2025-01-02T00:00:00Z');
+	t.is(result.entries[2]?.timestamp, '2025-01-03T00:00:00Z');
+});
+
+test('LogStorage: query generates facets', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry({level: 'error'}));
+	storage.addEntry(createLogEntry({level: 'error'}));
+	storage.addEntry(createLogEntry({level: 'info'}));
+
+	const result = storage.query({});
+
+	t.truthy(result.facets);
+	t.is(result.facets?.levels.error, 2);
+	t.is(result.facets?.levels.info, 1);
+});
+
+test('LogStorage: aggregate groups by level', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry({level: 'error'}));
+	storage.addEntry(createLogEntry({level: 'error'}));
+	storage.addEntry(createLogEntry({level: 'info'}));
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['count'],
+	};
+
+	const result = storage.aggregate(options);
+
+	t.is(result.totalGroups, 2);
+	t.is(result.groups.error?.count, 2);
+	t.is(result.groups.info?.count, 1);
+});
+
+test('LogStorage: aggregate calculates avgDuration', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(
+		createLogEntry({level: 'info', performance: {duration: 100}}),
+	);
+	storage.addEntry(
+		createLogEntry({level: 'info', performance: {duration: 200}}),
+	);
+	storage.addEntry(
+		createLogEntry({level: 'info', performance: {duration: 300}}),
+	);
+
+	const options: AggregationOptions = {
+		groupBy: 'level',
+		aggregations: ['avgDuration'],
+	};
+
+	const result = storage.aggregate(options);
+
+	t.is(result.groups.info?.avgDuration, 200);
+});
+
+test('LogStorage: clear removes all entries', t => {
+	const storage = new LogStorage(10);
+
+	storage.addEntry(createLogEntry());
+	storage.addEntry(createLogEntry());
+	storage.addEntry(createLogEntry());
+
+	t.is(storage.getEntryCount(), 3);
+
+	storage.clear();
+
+	t.is(storage.getEntryCount(), 0);
+	t.deepEqual(storage.query({}).entries, []);
+});
+
+test('LogStorage: integration test - full workflow', t => {
+	const storage = new LogStorage(100);
+
+	// Add various entries
+	storage.addEntry(
+		createLogEntry({
+			level: 'error',
+			message: 'Database error',
+			source: 'db-server',
+			timestamp: '2025-01-01T10:00:00Z',
+			performance: {duration: 1500},
+		}),
+	);
+	storage.addEntry(
+		createLogEntry({
+			level: 'error',
+			message: 'API timeout',
+			source: 'api-server',
+			timestamp: '2025-01-01T11:00:00Z',
+			performance: {duration: 3000},
+		}),
+	);
+	storage.addEntry(
+		createLogEntry({
+			level: 'info',
+			message: 'Request processed',
+			source: 'api-server',
+			timestamp: '2025-01-01T12:00:00Z',
+			performance: {duration: 200},
+		}),
+	);
+
+	// Query for errors
+	const errorQuery: LogQuery = {
+		levels: ['error'],
+		sortBy: 'duration',
+		sortOrder: 'desc',
+	};
+	const errorResult = storage.query(errorQuery);
+
+	t.is(errorResult.entries.length, 2);
+	t.is(errorResult.entries[0]?.message, 'API timeout'); // Longest duration
+	t.is(errorResult.entries[1]?.message, 'Database error');
+
+	// Aggregate by source
+	const aggOptions: AggregationOptions = {
+		groupBy: 'source',
+		aggregations: ['count', 'avgDuration'],
+	};
+	const aggResult = storage.aggregate(aggOptions);
+
+	t.is(aggResult.totalGroups, 2);
+	t.is(aggResult.groups['api-server']?.count, 2);
+	t.is(aggResult.groups['db-server']?.count, 1);
+	t.is(aggResult.groups['api-server']?.avgDuration, 1600); // (3000 + 200) / 2
+});
+
+test('LogStorage: handles wraparound in buffer', t => {
+	const storage = new LogStorage(3);
+
+	storage.addEntry(createLogEntry({message: '1'}));
+	storage.addEntry(createLogEntry({message: '2'}));
+	storage.addEntry(createLogEntry({message: '3'}));
+	storage.addEntry(createLogEntry({message: '4'})); // Should remove '1'
+
+	const result = storage.query({});
+
+	t.is(result.entries.length, 3);
+	t.is(result.totalCount, 3);
+	// First entry should be removed
+	t.false(result.entries.some(e => e.message === '1'));
+	t.true(result.entries.some(e => e.message === '4'));
+});