gitx.do 0.0.2 → 0.0.3

package/dist/storage/lru-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../../src/storage/lru-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../../src/storage/lru-cache.ts"],"names":[],"mappings":"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"}

package/dist/storage/lru-cache.js

@@ -1,9 +1,106 @@
 /**
- * LRU Cache implementation for hot objects in gitdo
- * gitdo-165: LRU cache for hot objects
+ * @fileoverview LRU Cache Implementation for Hot Objects
+ *
+ * This module provides a high-performance Least Recently Used (LRU) cache
+ * implementation optimized for storing frequently accessed Git objects.
+ *
+ * ## Features
+ *
+ * - **Dual Limits**: Supports both count-based and byte-size-based limits
+ * - **TTL Support**: Optional time-to-live for automatic entry expiration
+ * - **Eviction Callbacks**: Hook into eviction events for cleanup or analytics
+ * - **Statistics Tracking**: Built-in hit/miss tracking and hit rate calculation
+ * - **O(1) Operations**: All get/set/delete operations are O(1) using a doubly linked list
+ *
+ * ## Implementation Details
+ *
+ * The cache uses a combination of:
+ * - A Map for O(1) key lookup
+ * - A doubly linked list for O(1) LRU ordering
+ *
+ * When the cache exceeds its limits, the least recently used items are evicted.
+ * Items can also be evicted due to TTL expiration.
+ *
+ * @module storage/lru-cache
+ *
+ * @example
+ * ```typescript
+ * // Create a cache with 100 items max and 10MB size limit
+ * const cache = new LRUCache<string, Uint8Array>({
+ *   maxCount: 100,
+ *   maxBytes: 10 * 1024 * 1024,
+ *   defaultTTL: 3600000, // 1 hour
+ *   onEvict: (key, value, reason) => {
+ *     console.log(`Evicted ${key}: ${reason}`);
+ *   }
+ * });
+ *
+ * // Store and retrieve values
+ * cache.set('object-sha', objectData);
+ * const data = cache.get('object-sha');
+ *
+ * // Check statistics
+ * const stats = cache.getStats();
+ * console.log(`Hit rate: ${stats.hitRate}%`);
+ * ```
  */
 /**
- * LRU Cache class for storing hot objects with size and count limits
+ * LRU Cache class for storing hot objects with size and count limits.
+ *
+ * @description
+ * A high-performance Least Recently Used cache with the following features:
+ *
+ * - **O(1) Operations**: Get, set, and delete are all constant time
+ * - **Dual Limits**: Supports both count and byte-size limits
+ * - **TTL Support**: Optional per-entry or default time-to-live
+ * - **Eviction Events**: Callbacks when items are removed
+ * - **Statistics**: Track hits, misses, and evictions
+ *
+ * The cache maintains items in order of recent use. When the cache is full,
+ * the least recently used items are evicted first.
+ *
+ * ## Type Parameters
+ *
+ * - `K`: The type of cache keys (default: string)
+ * - `V`: The type of cached values (default: unknown)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with string keys and Uint8Array values
+ * const objectCache = new LRUCache<string, Uint8Array>({
+ *   maxCount: 1000,
+ *   maxBytes: 100 * 1024 * 1024 // 100MB
+ * });
+ *
+ * // Store a value
+ * objectCache.set(sha, objectData);
+ *
+ * // Retrieve a value (returns undefined if not found or expired)
+ * const data = objectCache.get(sha);
+ *
+ * // Check without affecting LRU order
+ * if (objectCache.has(sha)) {
+ *   const peeked = objectCache.peek(sha);
+ * }
+ *
+ * // Remove expired entries
+ * const pruned = objectCache.prune();
+ * console.log(`Removed ${pruned} expired entries`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With eviction callback for cleanup
+ * const cache = new LRUCache<string, Resource>({
+ *   maxCount: 100,
+ *   onEvict: (key, value, reason) => {
+ *     if (reason !== 'clear') {
+ *       value.dispose(); // Clean up resources
+ *     }
+ *     console.log(`Evicted ${key}: ${reason}`);
+ *   }
+ * });
+ * ```
  */
 export class LRUCache {
     cache = new Map();
@@ -19,8 +116,31 @@ export class LRUCache {
     sizeCalculator;
     onEvict;
     /**
-     * Create a new LRU cache
-     * @param options Configuration options
+     * Creates a new LRU cache instance.
+     *
+     * @description
+     * Initializes the cache with the specified options. All options have
+     * sensible defaults for unlimited caching.
+     *
+     * @param options - Configuration options for the cache
+     *
+     * @example
+     * ```typescript
+     * // Simple cache with count limit
+     * const cache = new LRUCache({ maxCount: 100 });
+     *
+     * // Cache with size limit and TTL
+     * const cache = new LRUCache({
+     *   maxBytes: 50 * 1024 * 1024, // 50MB
+     *   defaultTTL: 3600000 // 1 hour
+     * });
+     *
+     * // Cache with custom size calculator for Uint8Array
+     * const binaryCache = new LRUCache<string, Uint8Array>({
+     *   maxBytes: 100 * 1024 * 1024,
+     *   sizeCalculator: (arr) => arr.byteLength
+     * });
+     * ```
      */
     constructor(options) {
         this.maxCount = options?.maxCount ?? Infinity;
@@ -30,7 +150,12 @@ export class LRUCache {
         this.onEvict = options?.onEvict;
     }
     /**
-     * Check if an entry is expired
+     * Checks if an entry is expired.
+     *
+     * @param entry - The cache entry to check
+     * @returns true if the entry has expired
+     *
+     * @internal
      */
     isExpired(entry) {
         if (entry.expiresAt === null)
@@ -38,7 +163,11 @@ export class LRUCache {
         return Date.now() > entry.expiresAt;
     }
     /**
-     * Move a node to the head (most recently used)
+     * Moves a node to the head (most recently used position).
+     *
+     * @param node - The node to move
+     *
+     * @internal
      */
     moveToHead(node) {
         if (node === this.head)
@@ -57,7 +186,11 @@ export class LRUCache {
         }
     }
     /**
-     * Remove a node from the linked list
+     * Removes a node from the linked list.
+     *
+     * @param node - The node to remove
+     *
+     * @internal
      */
     removeNode(node) {
         if (node.prev) {
@@ -74,7 +207,11 @@ export class LRUCache {
         }
     }
     /**
-     * Add a node to the head of the list
+     * Adds a node to the head of the list.
+     *
+     * @param node - The node to add
+     *
+     * @internal
      */
     addToHead(node) {
         node.prev = null;
@@ -88,7 +225,11 @@ export class LRUCache {
         }
     }
     /**
-     * Evict items until we're under limits
+     * Evicts items until the cache can accommodate a new item.
+     *
+     * @param requiredSize - Size in bytes needed for the new item
+     *
+     * @internal
      */
     evictToFit(requiredSize) {
         // Evict until we have room for the new item
@@ -105,9 +246,25 @@ export class LRUCache {
         }
     }
     /**
-     * Get a value from the cache
-     * @param key The cache key
+     * Gets a value from the cache.
+     *
+     * @description
+     * Retrieves a value by key. If the key exists and hasn't expired,
+     * returns the value and moves the entry to the most recently used position.
+     * If the key doesn't exist or has expired, returns undefined.
+     *
+     * @param key - The cache key to look up
+     *
      * @returns The cached value or undefined if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const cache = new LRUCache<string, string>();
+     * cache.set('greeting', 'hello');
+     *
+     * const value = cache.get('greeting'); // 'hello'
+     * const missing = cache.get('nonexistent'); // undefined
+     * ```
      */
     get(key) {
         const node = this.cache.get(key);
@@ -133,11 +290,40 @@ export class LRUCache {
         return node.entry.value;
     }
     /**
-     * Set a value in the cache
-     * @param key The cache key
-     * @param value The value to cache
-     * @param options Optional settings for this entry
-     * @returns true if successfully set, false otherwise
+     * Sets a value in the cache.
+     *
+     * @description
+     * Stores a value with the given key. If the key already exists,
+     * updates the value. If storing the value would exceed limits,
+     * evicts least recently used items first.
+     *
+     * Returns false if the value is larger than maxBytes (cannot fit).
+     *
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param options - Optional per-entry settings (TTL, size)
+     *
+     * @returns true if successfully stored, false if value too large
+     *
+     * @example
+     * ```typescript
+     * const cache = new LRUCache<string, Uint8Array>({
+     *   maxBytes: 1024
+     * });
+     *
+     * // Basic set
+     * cache.set('key1', new Uint8Array([1, 2, 3]));
+     *
+     * // Set with custom TTL
+     * cache.set('key2', data, { ttl: 60000 }); // 1 minute
+     *
+     * // Set with explicit size
+     * cache.set('key3', complexObject, { size: 1000 });
+     *
+     * // Returns false if value too large
+     * const hugeData = new Uint8Array(10000);
+     * cache.set('huge', hugeData); // returns false
+     * ```
      */
     set(key, value, options) {
         const size = options?.size ?? this.sizeCalculator(value);
@@ -186,9 +372,23 @@ export class LRUCache {
         return true;
     }
     /**
-     * Check if a key exists in the cache (without updating LRU order)
-     * @param key The cache key
+     * Checks if a key exists in the cache.
+     *
+     * @description
+     * Returns true if the key exists and hasn't expired.
+     * Does NOT update LRU order (use peek() for that too).
+     *
+     * @param key - The cache key to check
+     *
      * @returns true if the key exists and is not expired
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('important-key')) {
+     *   // Key exists and is valid
+     *   const value = cache.get('important-key');
+     * }
+     * ```
      */
     has(key) {
         const node = this.cache.get(key);
@@ -199,9 +399,22 @@ export class LRUCache {
         return true;
     }
     /**
-     * Delete a key from the cache
-     * @param key The cache key
+     * Deletes a key from the cache.
+     *
+     * @description
+     * Removes an entry from the cache. Triggers the onEvict callback
+     * with reason 'manual'.
+     *
+     * @param key - The cache key to delete
+     *
      * @returns true if the key was deleted, false if it didn't exist
+     *
+     * @example
+     * ```typescript
+     * cache.set('key', 'value');
+     * cache.delete('key'); // returns true
+     * cache.delete('key'); // returns false (already deleted)
+     * ```
      */
     delete(key) {
         const node = this.cache.get(key);
@@ -216,7 +429,21 @@ export class LRUCache {
         return true;
     }
     /**
-     * Clear all entries from the cache
+     * Clears all entries from the cache.
+     *
+     * @description
+     * Removes all entries and resets the byte counter. If an onEvict
+     * callback is configured, it's called for each entry with reason 'clear'.
+     *
+     * Does NOT reset statistics (use resetStats() for that).
+     *
+     * @example
+     * ```typescript
+     * cache.set('a', 1);
+     * cache.set('b', 2);
+     * cache.clear();
+     * console.log(cache.size); // 0
+     * ```
      */
     clear() {
         if (this.onEvict) {
@@ -231,8 +458,21 @@ export class LRUCache {
         this._bytes = 0;
     }
     /**
-     * Get cache statistics
+     * Gets cache statistics.
+     *
+     * @description
+     * Returns current statistics about cache performance including
+     * hits, misses, item count, byte usage, evictions, and hit rate.
+     *
      * @returns Current cache statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = cache.getStats();
+     * console.log(`Hit rate: ${stats.hitRate}%`);
+     * console.log(`Cache size: ${stats.count} items, ${stats.bytes} bytes`);
+     * console.log(`Evictions: ${stats.evictions}`);
+     * ```
      */
     getStats() {
         const total = this._hits + this._misses;
@@ -247,7 +487,18 @@ export class LRUCache {
         };
     }
     /**
-     * Reset cache statistics (keeps cached data)
+     * Resets cache statistics.
+     *
+     * @description
+     * Resets hit, miss, and eviction counters to zero.
+     * Does NOT clear cached data.
+     *
+     * @example
+     * ```typescript
+     * // After warmup period, reset stats
+     * cache.resetStats();
+     * // Now stats reflect production traffic
+     * ```
      */
     resetStats() {
         this._hits = 0;
@@ -255,19 +506,47 @@ export class LRUCache {
         this._evictions = 0;
     }
     /**
-     * Get the number of items currently in the cache
+     * Gets the number of items currently in the cache.
+     *
+     * @returns Current item count
+     *
+     * @example
+     * ```typescript
+     * console.log(`Cache has ${cache.size} items`);
+     * ```
      */
     get size() {
         return this.cache.size;
     }
     /**
-     * Get the current byte size of the cache
+     * Gets the current byte size of the cache.
+     *
+     * @returns Current size in bytes
+     *
+     * @example
+     * ```typescript
+     * console.log(`Cache using ${cache.bytes} bytes`);
+     * ```
      */
     get bytes() {
         return this._bytes;
     }
     /**
-     * Get all keys in the cache (in LRU order, most recent first)
+     * Gets all keys in the cache in LRU order.
+     *
+     * @description
+     * Returns keys from most recently used to least recently used.
+     * Does NOT affect LRU ordering.
+     *
+     * @returns Array of keys in LRU order (most recent first)
+     *
+     * @example
+     * ```typescript
+     * cache.set('a', 1);
+     * cache.set('b', 2);
+     * cache.get('a');
+     * console.log(cache.keys()); // ['a', 'b']
+     * ```
      */
     keys() {
         const keys = [];
@@ -279,7 +558,18 @@ export class LRUCache {
         return keys;
     }
     /**
-     * Get all values in the cache (in LRU order, most recent first)
+     * Gets all values in the cache in LRU order.
+     *
+     * @description
+     * Returns values from most recently used to least recently used.
+     * Does NOT affect LRU ordering.
+     *
+     * @returns Array of values in LRU order (most recent first)
+     *
+     * @example
+     * ```typescript
+     * const recentValues = cache.values();
+     * ```
      */
     values() {
         const values = [];
@@ -291,7 +581,20 @@ export class LRUCache {
         return values;
     }
     /**
-     * Get all entries in the cache (in LRU order, most recent first)
+     * Gets all entries in the cache in LRU order.
+     *
+     * @description
+     * Returns [key, value] pairs from most recently used to least recently used.
+     * Does NOT affect LRU ordering.
+     *
+     * @returns Array of [key, value] pairs in LRU order
+     *
+     * @example
+     * ```typescript
+     * for (const [key, value] of cache.entries()) {
+     *   console.log(`${key}: ${value}`);
+     * }
+     * ```
      */
     entries() {
         const entries = [];
@@ -303,9 +606,22 @@ export class LRUCache {
         return entries;
     }
     /**
-     * Peek at a value without updating LRU order
-     * @param key The cache key
+     * Peeks at a value without updating LRU order.
+     *
+     * @description
+     * Retrieves a value without marking it as recently used.
+     * Useful for inspection or when you don't want to affect eviction order.
+     *
+     * @param key - The cache key to peek at
+     *
      * @returns The cached value or undefined if not found/expired
+     *
+     * @example
+     * ```typescript
+     * // Check value without affecting LRU order
+     * const value = cache.peek('key');
+     * // This won't prevent 'key' from being evicted next
+     * ```
      */
     peek(key) {
         const node = this.cache.get(key);
@@ -316,8 +632,27 @@ export class LRUCache {
         return node.entry.value;
     }
     /**
-     * Evict expired entries from the cache
+     * Evicts expired entries from the cache.
+     *
+     * @description
+     * Scans all entries and removes those that have expired.
+     * Triggers onEvict callback with reason 'ttl' for each removed entry.
+     *
+     * Call this periodically if you need proactive cleanup of expired entries.
+     * Note: Expired entries are also cleaned up lazily on get().
+     *
      * @returns Number of entries evicted
+     *
+     * @example
+     * ```typescript
+     * // Run periodic cleanup
+     * setInterval(() => {
+     *   const pruned = cache.prune();
+     *   if (pruned > 0) {
+     *     console.log(`Pruned ${pruned} expired entries`);
+     *   }
+     * }, 60000); // Every minute
+     * ```
      */
     prune() {
         let pruned = 0;
@@ -336,8 +671,22 @@ export class LRUCache {
         return pruned;
     }
     /**
-     * Resize the cache to new limits
-     * @param options New size limits
+     * Resizes the cache to new limits.
+     *
+     * @description
+     * Updates the maxCount and/or maxBytes limits. If the current cache
+     * exceeds the new limits, evicts LRU items until within limits.
+     *
+     * @param options - New size limits (maxCount and/or maxBytes)
+     *
+     * @example
+     * ```typescript
+     * // Reduce cache size under memory pressure
+     * cache.resize({ maxBytes: 10 * 1024 * 1024 }); // Reduce to 10MB
+     *
+     * // Increase limit when more memory is available
+     * cache.resize({ maxCount: 1000, maxBytes: 100 * 1024 * 1024 });
+     * ```
      */
     resize(options) {
         if (options.maxCount !== undefined) {
@@ -361,13 +710,67 @@ export class LRUCache {
     }
 }
 /**
- * Create a key serializer for complex key types
+ * Creates a key serializer for complex key types.
+ *
+ * @description
+ * Helper function for creating serializers when using complex key types
+ * that need to be converted to/from strings.
+ *
+ * @param serialize - Function to convert key to string
+ * @param deserialize - Function to convert string back to key
+ *
+ * @returns Object with serialize and deserialize functions
+ *
+ * @example
+ * ```typescript
+ * interface ObjectKey {
+ *   repo: string;
+ *   sha: string;
+ * }
+ *
+ * const keySerializer = createKeySerializer<ObjectKey>(
+ *   (key) => `${key.repo}:${key.sha}`,
+ *   (str) => {
+ *     const [repo, sha] = str.split(':');
+ *     return { repo, sha };
+ *   }
+ * );
+ *
+ * // Use with cache
+ * const serializedKey = keySerializer.serialize({ repo: 'foo', sha: 'abc' });
+ * cache.set(serializedKey, value);
+ * ```
  */
 export function createKeySerializer(serialize, deserialize) {
     return { serialize, deserialize };
 }
 /**
- * Default size calculator for common value types
+ * Default size calculator for common value types.
+ *
+ * @description
+ * Estimates the byte size of common JavaScript value types:
+ * - `null/undefined`: 0 bytes
+ * - `string`: 2 bytes per character (UTF-16)
+ * - `number`: 8 bytes
+ * - `boolean`: 4 bytes
+ * - `Uint8Array/ArrayBuffer`: actual byteLength
+ * - `object`: JSON-serialized length * 2
+ * - `unknown`: 8 bytes (default)
+ *
+ * For more accurate size calculation with specific types,
+ * provide a custom sizeCalculator in CacheOptions.
+ *
+ * @param value - The value to calculate size for
+ *
+ * @returns Estimated size in bytes
+ *
+ * @example
+ * ```typescript
+ * defaultSizeCalculator('hello'); // 10 (5 chars * 2)
+ * defaultSizeCalculator(42); // 8
+ * defaultSizeCalculator(new Uint8Array(100)); // 100
+ * defaultSizeCalculator({ key: 'value' }); // ~30
+ * ```
  */
 export function defaultSizeCalculator(value) {
     if (value === null || value === undefined) {