@gguf/coder 0.3.0 → 0.3.1

package/source/utils/bounded-map.spec.ts

@@ -0,0 +1,300 @@
+import test from 'ava';
+import {BoundedMap} from './bounded-map';
+
+test('BoundedMap - basic set and get operations', t => {
+	const map = new BoundedMap<string, number>();
+
+	map.set('a', 1);
+	map.set('b', 2);
+	map.set('c', 3);
+
+	t.is(map.get('a'), 1);
+	t.is(map.get('b'), 2);
+	t.is(map.get('c'), 3);
+	t.is(map.get('nonexistent'), undefined);
+});
+
+test('BoundedMap - has() method', t => {
+	const map = new BoundedMap<string, number>();
+
+	map.set('a', 1);
+
+	t.true(map.has('a'));
+	t.false(map.has('nonexistent'));
+});
+
+test('BoundedMap - delete() method', t => {
+	const map = new BoundedMap<string, number>();
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	t.true(map.delete('a'));
+	t.false(map.has('a'));
+	t.true(map.has('b'));
+	t.false(map.delete('nonexistent'));
+});
+
+test('BoundedMap - clear() method', t => {
+	const map = new BoundedMap<string, number>();
+
+	map.set('a', 1);
+	map.set('b', 2);
+	map.set('c', 3);
+
+	t.is(map.size, 3);
+	map.clear();
+	t.is(map.size, 0);
+	t.false(map.has('a'));
+});
+
+test('BoundedMap - enforces max size limit', t => {
+	const map = new BoundedMap<string, number>({maxSize: 3});
+
+	map.set('a', 1);
+	map.set('b', 2);
+	map.set('c', 3);
+	t.is(map.size, 3);
+
+	// Adding 4th element should evict oldest ('a')
+	map.set('d', 4);
+	t.is(map.size, 3);
+	t.false(map.has('a')); // Oldest entry evicted
+	t.true(map.has('b'));
+	t.true(map.has('c'));
+	t.true(map.has('d'));
+});
+
+test('BoundedMap - evicts oldest entry first', t => {
+	const map = new BoundedMap<string, number>({maxSize: 2});
+
+	map.set('first', 1);
+	map.set('second', 2);
+	map.set('third', 3);
+
+	// 'first' should be evicted
+	t.false(map.has('first'));
+	t.true(map.has('second'));
+	t.true(map.has('third'));
+});
+
+test('BoundedMap - updating existing key does not trigger eviction', t => {
+	const map = new BoundedMap<string, number>({maxSize: 2});
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	// Update existing key
+	map.set('a', 10);
+
+	// Should still have both entries
+	t.is(map.size, 2);
+	t.is(map.get('a'), 10);
+	t.is(map.get('b'), 2);
+});
+
+test('BoundedMap - TTL causes entries to expire', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 50, // 50ms TTL
+	});
+
+	map.set('a', 1);
+	t.is(map.get('a'), 1);
+
+	// Wait for TTL to expire
+	await new Promise(resolve => setTimeout(resolve, 60));
+
+	// Entry should be expired
+	t.is(map.get('a'), undefined);
+	t.false(map.has('a'));
+});
+
+test('BoundedMap - entries within TTL are accessible', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 100, // 100ms TTL
+	});
+
+	map.set('a', 1);
+
+	// Wait less than TTL
+	await new Promise(resolve => setTimeout(resolve, 50));
+
+	// Entry should still be accessible
+	t.is(map.get('a'), 1);
+	t.true(map.has('a'));
+});
+
+test('BoundedMap - keys() returns non-expired keys', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 50, // 50ms TTL
+	});
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	await new Promise(resolve => setTimeout(resolve, 60));
+
+	map.set('c', 3); // Add after expiration
+
+	const keys = Array.from(map.keys());
+	t.deepEqual(keys, ['c']);
+});
+
+test('BoundedMap - values() returns non-expired values', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 50,
+	});
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	await new Promise(resolve => setTimeout(resolve, 60));
+
+	map.set('c', 3);
+
+	const values = Array.from(map.values());
+	t.deepEqual(values, [3]);
+});
+
+test('BoundedMap - entries() returns non-expired entries', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 50,
+	});
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	await new Promise(resolve => setTimeout(resolve, 60));
+
+	map.set('c', 3);
+
+	const entries = Array.from(map.entries());
+	t.deepEqual(entries, [['c', 3]]);
+});
+
+test('BoundedMap - forEach iterates over non-expired entries', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 50,
+	});
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	await new Promise(resolve => setTimeout(resolve, 60));
+
+	map.set('c', 3);
+
+	const entries: Array<[string, number]> = [];
+	map.forEach((value, key) => {
+		entries.push([key, value]);
+	});
+
+	t.deepEqual(entries, [['c', 3]]);
+});
+
+test('BoundedMap - is iterable', t => {
+	const map = new BoundedMap<string, number>();
+
+	map.set('a', 1);
+	map.set('b', 2);
+	map.set('c', 3);
+
+	const entries = Array.from(map);
+	t.deepEqual(entries, [
+		['a', 1],
+		['b', 2],
+		['c', 3],
+	]);
+});
+
+test('BoundedMap - getRawSize() returns size including expired entries', async t => {
+	const map = new BoundedMap<string, number>({
+		maxSize: 100,
+		ttl: 50,
+	});
+
+	map.set('a', 1);
+	map.set('b', 2);
+
+	await new Promise(resolve => setTimeout(resolve, 60));
+
+	// Entries are expired but not yet cleaned up
+	t.is(map.getRawSize(), 2);
+
+	// Accessing keys() triggers cleanup
+	Array.from(map.keys());
+	t.is(map.getRawSize(), 0);
+});
+
+test('BoundedMap - throws error if maxSize is 0 or negative', t => {
+	t.throws(
+		() => {
+			new BoundedMap({maxSize: 0});
+		},
+		{message: 'maxSize must be greater than 0'},
+	);
+
+	t.throws(
+		() => {
+			new BoundedMap({maxSize: -1});
+		},
+		{message: 'maxSize must be greater than 0'},
+	);
+});
+
+test('BoundedMap - default maxSize is 1000', t => {
+	const map = new BoundedMap<string, number>();
+
+	// Fill with 1000 entries
+	for (let i = 0; i < 1000; i++) {
+		map.set(`key${i}`, i);
+	}
+
+	t.is(map.size, 1000);
+
+	// Adding 1001st entry should evict first
+	map.set('key1000', 1000);
+	t.is(map.size, 1000);
+	t.false(map.has('key0'));
+	t.true(map.has('key1000'));
+});
+
+test('BoundedMap - works with different key/value types', t => {
+	const numberMap = new BoundedMap<number, string>();
+	numberMap.set(1, 'one');
+	numberMap.set(2, 'two');
+	t.is(numberMap.get(1), 'one');
+
+	const objectMap = new BoundedMap<string, {value: number}>();
+	objectMap.set('a', {value: 1});
+	t.deepEqual(objectMap.get('a'), {value: 1});
+});
+
+test('BoundedMap - set() returns this for chaining', t => {
+	const map = new BoundedMap<string, number>();
+
+	const result = map.set('a', 1).set('b', 2).set('c', 3);
+
+	t.is(result, map);
+	t.is(map.size, 3);
+});
+
+test('BoundedMap - no TTL when ttl is 0 or undefined', async t => {
+	const map1 = new BoundedMap<string, number>({ttl: 0});
+	const map2 = new BoundedMap<string, number>({ttl: undefined});
+
+	map1.set('a', 1);
+	map2.set('b', 2);
+
+	await new Promise(resolve => setTimeout(resolve, 100));
+
+	// Entries should not expire
+	t.is(map1.get('a'), 1);
+	t.is(map2.get('b'), 2);
+});

package/source/utils/bounded-map.ts

@@ -0,0 +1,193 @@
+/**
+ * BoundedMap - A Map with size and TTL constraints to prevent unbounded memory growth
+ *
+ * Features:
+ * - Maximum size limit with automatic eviction of oldest entries
+ * - Optional TTL (time-to-live) for automatic expiration
+ * - Maintains insertion order for predictable eviction
+ */
+
+interface BoundedMapEntry<V> {
+	value: V;
+	timestamp: number;
+}
+
+export interface BoundedMapOptions {
+	/**
+	 * Maximum number of entries. When exceeded, oldest entries are removed.
+	 * @default 1000
+	 */
+	maxSize?: number;
+
+	/**
+	 * Time-to-live in milliseconds. Entries older than this are automatically removed.
+	 * Set to 0 or undefined to disable TTL.
+	 * @default undefined (no TTL)
+	 */
+	ttl?: number;
+}
+
+/**
+ * A Map implementation with automatic size limiting and optional TTL
+ */
+export class BoundedMap<K, V> {
+	private map: Map<K, BoundedMapEntry<V>>;
+	private maxSize: number;
+	private ttl?: number;
+
+	constructor(options: BoundedMapOptions = {}) {
+		this.map = new Map();
+		this.maxSize = options.maxSize ?? 1000;
+		this.ttl = options.ttl;
+
+		if (this.maxSize <= 0) {
+			throw new Error('maxSize must be greater than 0');
+		}
+	}
+
+	/**
+	 * Set a key-value pair, enforcing size limit
+	 */
+	set(key: K, value: V): this {
+		// Remove oldest entry if at capacity
+		if (this.map.size >= this.maxSize && !this.map.has(key)) {
+			const firstKey = this.map.keys().next().value;
+			if (firstKey !== undefined) {
+				this.map.delete(firstKey);
+			}
+		}
+
+		this.map.set(key, {
+			value,
+			timestamp: Date.now(),
+		});
+
+		return this;
+	}
+
+	/**
+	 * Get a value by key, checking TTL if configured
+	 */
+	get(key: K): V | undefined {
+		const entry = this.map.get(key);
+		if (!entry) {
+			return undefined;
+		}
+
+		// Check TTL if configured
+		if (this.ttl !== undefined && this.ttl > 0) {
+			const age = Date.now() - entry.timestamp;
+			if (age > this.ttl) {
+				this.map.delete(key);
+				return undefined;
+			}
+		}
+
+		return entry.value;
+	}
+
+	/**
+	 * Check if key exists and is not expired
+	 */
+	has(key: K): boolean {
+		return this.get(key) !== undefined;
+	}
+
+	/**
+	 * Delete a key-value pair
+	 */
+	delete(key: K): boolean {
+		return this.map.delete(key);
+	}
+
+	/**
+	 * Clear all entries
+	 */
+	clear(): void {
+		this.map.clear();
+	}
+
+	/**
+	 * Get number of entries (including potentially expired ones)
+	 */
+	get size(): number {
+		return this.map.size;
+	}
+
+	/**
+	 * Get all non-expired keys
+	 */
+	keys(): IterableIterator<K> {
+		this.cleanupExpired();
+		return this.map.keys();
+	}
+
+	/**
+	 * Get all non-expired values
+	 */
+	*values(): IterableIterator<V> {
+		this.cleanupExpired();
+		for (const entry of this.map.values()) {
+			yield entry.value;
+		}
+	}
+
+	/**
+	 * Get all non-expired entries as [key, value] pairs
+	 */
+	*entries(): IterableIterator<[K, V]> {
+		this.cleanupExpired();
+		for (const [key, entry] of this.map.entries()) {
+			yield [key, entry.value];
+		}
+	}
+
+	/**
+	 * Iterate over non-expired entries
+	 */
+	forEach(
+		callbackfn: (value: V, key: K, map: BoundedMap<K, V>) => void,
+		thisArg?: unknown,
+	): void {
+		this.cleanupExpired();
+		for (const [key, entry] of this.map.entries()) {
+			callbackfn.call(thisArg, entry.value, key, this);
+		}
+	}
+
+	/**
+	 * Remove all expired entries based on TTL
+	 */
+	private cleanupExpired(): void {
+		if (!this.ttl || this.ttl <= 0) {
+			return;
+		}
+
+		const now = Date.now();
+		const keysToDelete: K[] = [];
+
+		for (const [key, entry] of this.map.entries()) {
+			if (now - entry.timestamp > this.ttl) {
+				keysToDelete.push(key);
+			}
+		}
+
+		for (const key of keysToDelete) {
+			this.map.delete(key);
+		}
+	}
+
+	/**
+	 * Get all entries including expired ones (for debugging)
+	 */
+	getRawSize(): number {
+		return this.map.size;
+	}
+
+	/**
+	 * Make BoundedMap iterable
+	 */
+	[Symbol.iterator](): IterableIterator<[K, V]> {
+		return this.entries();
+	}
+}

package/source/utils/checkpoint-utils.spec.ts

@@ -0,0 +1,222 @@
+import test from 'ava';
+import {formatRelativeTime, validateCheckpointName} from './checkpoint-utils';
+
+// formatRelativeTime tests
+test('formatRelativeTime returns "Just now" for timestamps less than a minute ago', t => {
+	const now = new Date().toISOString();
+	t.is(formatRelativeTime(now), 'Just now');
+});
+
+test('formatRelativeTime returns mins ago for timestamps within the hour', t => {
+	const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+	t.is(formatRelativeTime(fiveMinutesAgo), '5 mins ago');
+});
+
+test('formatRelativeTime returns singular minute for 1 min ago', t => {
+	const oneMinuteAgo = new Date(Date.now() - 1 * 60 * 1000).toISOString();
+	t.is(formatRelativeTime(oneMinuteAgo), '1 min ago');
+});
+
+test('formatRelativeTime returns hours ago for timestamps within the day', t => {
+	const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+	t.is(formatRelativeTime(threeHoursAgo), '3 hrs ago');
+});
+
+test('formatRelativeTime returns singular hr for 1 hr ago', t => {
+	const oneHourAgo = new Date(Date.now() - 1 * 60 * 60 * 1000).toISOString();
+	t.is(formatRelativeTime(oneHourAgo), '1 hr ago');
+});
+
+test('formatRelativeTime returns days ago for timestamps within the week', t => {
+	const twoDaysAgo = new Date(
+		Date.now() - 2 * 24 * 60 * 60 * 1000,
+	).toISOString();
+	t.is(formatRelativeTime(twoDaysAgo), '2 days ago');
+});
+
+test('formatRelativeTime returns singular day for 1 day ago', t => {
+	const oneDayAgo = new Date(
+		Date.now() - 1 * 24 * 60 * 60 * 1000,
+	).toISOString();
+	t.is(formatRelativeTime(oneDayAgo), '1 day ago');
+});
+
+test('formatRelativeTime returns locale date string for timestamps older than a week', t => {
+	const twoWeeksAgo = new Date(
+		Date.now() - 14 * 24 * 60 * 60 * 1000,
+	).toISOString();
+	const result = formatRelativeTime(twoWeeksAgo);
+	// Should be a date string, not a relative time
+	t.false(result.includes('ago'));
+	t.false(result.includes('Just now'));
+});
+
+// validateCheckpointName tests - valid names
+test('validateCheckpointName accepts valid simple name', t => {
+	const result = validateCheckpointName('my-checkpoint');
+	t.true(result.valid);
+	t.is(result.error, undefined);
+});
+
+test('validateCheckpointName accepts name with numbers', t => {
+	const result = validateCheckpointName('checkpoint-v1');
+	t.true(result.valid);
+});
+
+test('validateCheckpointName accepts name with underscores', t => {
+	const result = validateCheckpointName('my_checkpoint_name');
+	t.true(result.valid);
+});
+
+test('validateCheckpointName accepts name with spaces', t => {
+	const result = validateCheckpointName('my checkpoint name');
+	t.true(result.valid);
+});
+
+// validateCheckpointName tests - empty/whitespace
+test('validateCheckpointName rejects empty string', t => {
+	const result = validateCheckpointName('');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name cannot be empty');
+});
+
+test('validateCheckpointName rejects whitespace-only string', t => {
+	const result = validateCheckpointName('   ');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name cannot be empty');
+});
+
+// validateCheckpointName tests - length
+test('validateCheckpointName accepts name at max length (100 chars)', t => {
+	const name = 'a'.repeat(100);
+	const result = validateCheckpointName(name);
+	t.true(result.valid);
+});
+
+test('validateCheckpointName rejects name over max length', t => {
+	const name = 'a'.repeat(101);
+	const result = validateCheckpointName(name);
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name must be 100 characters or less');
+});
+
+// validateCheckpointName tests - invalid characters
+test('validateCheckpointName rejects name with forward slash', t => {
+	const result = validateCheckpointName('my/checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+test('validateCheckpointName rejects name with backslash', t => {
+	const result = validateCheckpointName('my\\checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+test('validateCheckpointName rejects name with colon', t => {
+	const result = validateCheckpointName('my:checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+test('validateCheckpointName rejects name with asterisk', t => {
+	const result = validateCheckpointName('my*checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+test('validateCheckpointName rejects name with question mark', t => {
+	const result = validateCheckpointName('my?checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+test('validateCheckpointName rejects name with quotes', t => {
+	const result = validateCheckpointName('my"checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+test('validateCheckpointName rejects name with angle brackets', t => {
+	const result1 = validateCheckpointName('my<checkpoint');
+	const result2 = validateCheckpointName('my>checkpoint');
+	t.false(result1.valid);
+	t.false(result2.valid);
+});
+
+test('validateCheckpointName rejects name with pipe', t => {
+	const result = validateCheckpointName('my|checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name contains invalid characters');
+});
+
+// validateCheckpointName tests - reserved names (Windows)
+test('validateCheckpointName rejects CON (case insensitive)', t => {
+	const result1 = validateCheckpointName('CON');
+	const result2 = validateCheckpointName('con');
+	const result3 = validateCheckpointName('Con');
+	t.false(result1.valid);
+	t.false(result2.valid);
+	t.false(result3.valid);
+	t.is(result1.error, 'Checkpoint name is reserved by the system');
+});
+
+test('validateCheckpointName rejects PRN', t => {
+	const result = validateCheckpointName('PRN');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name is reserved by the system');
+});
+
+test('validateCheckpointName rejects AUX', t => {
+	const result = validateCheckpointName('AUX');
+	t.false(result.valid);
+});
+
+test('validateCheckpointName rejects NUL', t => {
+	const result = validateCheckpointName('NUL');
+	t.false(result.valid);
+});
+
+test('validateCheckpointName rejects COM ports', t => {
+	for (let i = 1; i <= 9; i++) {
+		const result = validateCheckpointName(`COM${i}`);
+		t.false(result.valid, `COM${i} should be rejected`);
+	}
+});
+
+test('validateCheckpointName rejects LPT ports', t => {
+	for (let i = 1; i <= 9; i++) {
+		const result = validateCheckpointName(`LPT${i}`);
+		t.false(result.valid, `LPT${i} should be rejected`);
+	}
+});
+
+// validateCheckpointName tests - dot/space at start/end
+test('validateCheckpointName rejects name starting with dot', t => {
+	const result = validateCheckpointName('.hidden');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name cannot start or end with a dot or space');
+});
+
+test('validateCheckpointName rejects name ending with dot', t => {
+	const result = validateCheckpointName('checkpoint.');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name cannot start or end with a dot or space');
+});
+
+test('validateCheckpointName rejects name starting with space', t => {
+	const result = validateCheckpointName(' checkpoint');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name cannot start or end with a dot or space');
+});
+
+test('validateCheckpointName rejects name ending with space', t => {
+	const result = validateCheckpointName('checkpoint ');
+	t.false(result.valid);
+	t.is(result.error, 'Checkpoint name cannot start or end with a dot or space');
+});
+
+test('validateCheckpointName accepts name with dot in middle', t => {
+	const result = validateCheckpointName('checkpoint.v1');
+	t.true(result.valid);
+});