{"id":49756980,"url":"https://github.com/damiaoterto/mussurana_cache","last_synced_at":"2026-05-10T22:58:21.108Z","repository":{"id":260844611,"uuid":"882474776","full_name":"damiaoterto/mussurana_cache","owner":"damiaoterto","description":"High-performance in-memory cache system for Node.js written in Rust","archived":false,"fork":false,"pushed_at":"2025-05-02T14:50:42.000Z","size":782,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-10T22:58:09.009Z","etag":null,"topics":["napi","napi-rs","node-addon","nodejs","rust"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/damiaoterto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-02T21:46:14.000Z","updated_at":"2025-05-02T16:58:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"5a828bf1-c1f6-4fbc-9339-97737fb745ad","html_url":"https://github.com/damiaoterto/mussurana_cache","commit_stats":null,"previous_names":["damiaoterto/mussurana_cache"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/damiaoterto/mussurana_cache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiaoterto%2Fmussurana_cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiaoterto%2Fmussurana_cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiaoterto%2Fmussurana_cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiaoterto%2Fmussurana_cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/damiaoterto","download_url":"https://codeload.github.com/damiaoterto/mussurana_cache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiaoterto%2Fmussurana_cache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32874701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"ssl_error","status_checked_at":"2026-05-10T13:40:02.145Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["napi","napi-rs","node-addon","nodejs","rust"],"created_at":"2026-05-10T22:58:20.588Z","updated_at":"2026-05-10T22:58:21.103Z","avatar_url":"https://github.com/damiaoterto.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mussurana Cache\n\nA high-performance in-memory cache implementation for Node.js, written in Rust using napi-rs. Mussurana Cache provides efficient memory management, TTL support, and priority-based eviction policies.\n\n## Features\n\n- 🚀 High-performance Rust implementation\n- 💾 Configurable memory limits\n- ⏰ TTL (Time To Live) support\n- 🎯 Priority-based cache eviction\n- 📊 Cache statistics\n- 🧵 Thread-safe operations\n- 🔄 Automatic cleanup of expired items\n\n## Installation\n\n```bash\nnpm install mussurana-cache\n```\n\n## Quick Start\n\n```typescript\nimport { MussuranaCache, createMemoryUnits } from 'mussurana-cache';\n\n// optional utility\nconst memory = createMemoryUnits()\n\n// Create a new cache instance\nconst cache = new MussuranaCache({\n    maxMemory: memory.mb * 100, // 100MB or 100 * 1024 * 1024\n    maxItems: 10000,              // Maximum number of items\n    checkPeriod: 60000           // Cleanup interval in milliseconds\n});\n\n// Set a value with TTL and priority\ncache.set('key', 'value', 3600, 200); // TTL: 1 hour, High priority\n\n// Get a value\nconst value = cache.get('key');\n\n// Delete a value\ncache.delete('key');\n\n// Get cache statistics\nconst stats = cache.getStats();\nconsole.log('Cache Stats:', stats);\n```\n\n## API Reference\n\n### Constructor Options\n\n```typescript\ninterface CacheOptions {\n    maxMemory?: number;   // Maximum memory in bytes (default: 100MB)\n    maxItems?: number;    // Maximum number of items (default: 10000)\n    checkPeriod?: number; // Cleanup interval in ms (default: 60000)\n}\n```\n\n### Methods\n\n#### `set(key: string, value: string, ttl?: number, priority?: number): boolean`\n\nStores a value in the cache.\n\n- `key`: The key to store the value under\n- `value`: The value to store\n- `ttl`: Time to live in seconds (optional)\n- `priority`: Priority level 0-255 (optional, default: 128)\n- Returns: `boolean` indicating success\n\n#### `get(key: string): string | null`\n\nRetrieves a value from the cache.\n\n- `key`: The key to retrieve\n- Returns: The stored value or null if not found/expired\n\n#### `delete(key: string): boolean`\n\nRemoves a value from the cache.\n\n- `key`: The key to delete\n- Returns: `boolean` indicating whether the key existed\n\n#### `clear(): void`\n\nClears all items from the cache.\n\n#### `getStats(): CacheStats`\n\nReturns current cache statistics.\n\n```typescript\ninterface CacheStats {\n    memory_used: number;  // Current memory usage in bytes\n    items_count: number;  // Number of items in cache\n    hits: number;        // Number of successful gets\n    misses: number;      // Number of failed gets\n}\n```\n\n## Memory Management\n\nMussurana Cache uses a sophisticated memory management system:\n\n1. **Memory Limit**: Ensures the cache never exceeds the specified memory limit\n2. **Priority-based Eviction**: When memory is full, items with lower priority are evicted first\n3. **TTL Cleanup**: Automatically removes expired items during the cleanup cycle\n4. **Size Tracking**: Accurately tracks memory usage of stored items\n\n## Priority System\n\nThe priority system ranges from 0 to 255:\n- 0: Lowest priority (first to be evicted)\n- 128: Default priority\n- 255: Highest priority (last to be evicted)\n\nWhen the cache is full, items are evicted based on:\n1. Priority (lower priority items first)\n2. Age (older items first when priorities are equal)\n\n## Performance Considerations\n\n- Written in Rust for maximum performance\n- Uses efficient data structures and algorithms\n- Thread-safe operations via Rust's mutex implementation\n- Minimal overhead for memory tracking\n- Optimized for high-throughput scenarios\n\n## Example: Caching User Data\n\n```typescript\nimport { MussuranaCache } from 'mussurana-cache';\n\nconst cache = new MussuranaCache({\n    maxMemory: 200 * 1024 * 1024  // 200MB\n});\n\n// Cache user data with different priorities\nfunction cacheUserData(userId: string, data: string, isPremium: boolean) {\n    const priority = isPremium ? 200 : 100; // Higher priority for premium users\n    const ttl = 3600; // 1 hour cache\n    return cache.set(userId, data, ttl, priority);\n}\n\n// Get user data\nfunction getUserData(userId: string): string | null {\n    return cache.get(userId);\n}\n\n// Monitor cache performance\nsetInterval(() =\u003e {\n    const stats = cache.getStats();\n    console.log('Cache Performance:', {\n        memoryUsedMB: stats.memory_used / (1024 * 1024),\n        items: stats.items_count,\n        hitRatio: (stats.hits / (stats.hits + stats.misses)) * 100\n    });\n}, 60000);\n```\n\n## Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/mussurana.git\ncd mussurana\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Why \"Mussurana\"?\n\nThe name choice reflects both our Northeastern Brazilian heritage and the cache's behavior:\n\n- **Efficiency**: Like the Mussurana snake that helps control other snake populations, our cache efficiently manages memory by removing less important data\n- **Adaptation**: Just as the Mussurana adapts to different environments, our cache adapts to various memory constraints\n- **Natural Balance**: The snake maintains ecological balance; similarly, our cache maintains memory balance\n- **Cultural Heritage**: Represents the rich vocabulary and fauna of Northeastern Brazil\n\n\u003e \"Mussurana\" comes from the Tupi language, where \"muçu\" means snake and \"rana\" means similar to. This etymology reflects Brazil's indigenous heritage, particularly strong in the Northeast.\n\n\n## Cultural Note\n\nThis project is part of a broader initiative to bring Brazilian, particularly Northeastern Brazilian, technology to the global stage. We believe that by embracing our cultural identity while delivering high-quality software, we can enrich the global tech community with our unique perspective and solutions.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License\n\n## Acknowledgments\n\n- Built with [napi-rs](https://napi.rs/)\n- Inspired by modern cache implementations\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamiaoterto%2Fmussurana_cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdamiaoterto%2Fmussurana_cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamiaoterto%2Fmussurana_cache/lists"}