{"_id":"@beniwalsanjay/egenome-libs","_rev":"2-5e131cd8db0298c2fbd49092d3804437","name":"@beniwalsanjay/egenome-libs","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@beniwalsanjay/egenome-libs","version":"1.0.0","keywords":["typescript","library","solid","template"],"author":{"name":"sanjaybeniwal"},"license":"ISC","_id":"@beniwalsanjay/egenome-libs@1.0.0","maintainers":[{"name":"sanjaybeniwal","email":"beniwal1511@gmail.com"}],"homepage":"https://github.com/beniwalsanjay/egenome-libs#readme","bugs":{"url":"https://github.com/beniwalsanjay/egenome-libs/issues"},"dist":{"shasum":"4b355e1a1fc06a951fd8be07d380d050deb53457","tarball":"https://registry.npmjs.org/@beniwalsanjay/egenome-libs/-/egenome-libs-1.0.0.tgz","fileCount":9,"integrity":"sha512-hjffef+dLkgf7KuS2QoR/dQP1T3x1mqsqsgrj9NURKf+GdSPXYWaAiNEQmp0a+QWKmeJjfAth/1O2FKqlsRA0Q==","signatures":[{"sig":"MEQCICyX6mQAo8177gDK3knYP/mklgpl8gOdd/Gll/ErxPLpAiBDW4WVfwXlstHmtEeID/J0q3s1+pbQOekdBNcfOwz1cg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":602460},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"b7a5a82191373b020cc6750a705b2a0cae308193","scripts":{"dev":"tsup src/index.ts --dts --format esm,cjs --sourcemap --watch","lint":"eslint . --ext .ts,.tsx","test":"vitest run","build":"tsup src/index.ts --dts --format esm,cjs --sourcemap --clean","release":"semantic-release","test:watch":"vitest","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"sanjaybeniwal","email":"beniwal1511@gmail.com"},"repository":{"url":"git+https://github.com/beniwalsanjay/egenome-libs.git","type":"git"},"_npmVersion":"11.5.1","description":"A scalable TypeScript library for eGenome.","directories":{},"sideEffects":false,"_nodeVersion":"24.7.0","dependencies":{"inversify":"^6.0.2","reflect-metadata":"^0.2.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","eslint":"^8.57.0","vitest":"^2.0.5","prettier":"^3.3.3","typescript":"^5.5.4","@types/node":"^20.11.30","semantic-release":"^23.0.0","eslint-plugin-jsdoc":"^48.2.7","eslint-plugin-import":"^2.29.1","@semantic-release/git":"^10.0.1","@semantic-release/npm":"^12.0.0","eslint-config-prettier":"^9.1.0","@typescript-eslint/parser":"^7.0.0","@semantic-release/changelog":"^6.0.3","eslint-plugin-unused-imports":"^3.1.0","@typescript-eslint/eslint-plugin":"^7.0.0"},"peerDependencies":{"ioredis":"^5.3.0"},"optionalDependencies":{"ioredis":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/egenome-libs_1.0.0_1756812052868_0.540555189197578","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@beniwalsanjay/egenome-libs","version":"1.0.1","description":"A scalable TypeScript library for eGenome.","license":"ISC","author":{"name":"sanjaybeniwal"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"sideEffects":false,"scripts":{"build":"tsup src/index.ts --dts --format esm,cjs --sourcemap --clean","dev":"tsup src/index.ts --dts --format esm,cjs --sourcemap --watch","lint":"eslint . --ext .ts,.tsx","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build && npm run test","release":"semantic-release"},"peerDependencies":{"ioredis":"^5.3.0"},"dependencies":{"inversify":"^6.0.2","reflect-metadata":"^0.2.2"},"optionalDependencies":{"ioredis":"^5.3.0"},"devDependencies":{"@types/node":"^20.11.30","@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","eslint":"^8.57.0","eslint-config-prettier":"^9.1.0","eslint-plugin-import":"^2.29.1","eslint-plugin-jsdoc":"^48.2.7","eslint-plugin-unused-imports":"^3.1.0","prettier":"^3.3.3","tsup":"^8.0.2","typescript":"^5.5.4","vitest":"^2.0.5","semantic-release":"^23.0.0","@semantic-release/changelog":"^6.0.3","@semantic-release/git":"^10.0.1","@semantic-release/npm":"^12.0.0"},"engines":{"node":">=18"},"keywords":["typescript","library","solid","template"],"repository":{"type":"git","url":"git+https://github.com/beniwalsanjay/egenome-libs.git"},"bugs":{"url":"https://github.com/beniwalsanjay/egenome-libs/issues"},"homepage":"https://github.com/beniwalsanjay/egenome-libs#readme","_id":"@beniwalsanjay/egenome-libs@1.0.1","gitHead":"5a5c0cce9661440b12adb24cab2df7dd4e891e91","_nodeVersion":"24.7.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-CfAooyyoUEj2LFCp3hET3x+oUNNZQlez1AYalgVnEs29FE4VnQilquPr99iWz2AZE24PAzSLVmkAWy3vXlkahA==","shasum":"7e3697a1e852afee6686c72f5f647b4fca0f0176","tarball":"https://registry.npmjs.org/@beniwalsanjay/egenome-libs/-/egenome-libs-1.0.1.tgz","fileCount":9,"unpackedSize":602576,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDjkYYl63F5geQ5A1LEboEcFwJLgeisD4bM+ulbu46WsQIgTtroImW0KeMoJ8oajzUfWXgGtF6L0VpmMAIOCgwmhF4="}]},"_npmUser":{"name":"sanjaybeniwal","email":"beniwal1511@gmail.com"},"directories":{},"maintainers":[{"name":"sanjaybeniwal","email":"beniwal1511@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/egenome-libs_1.0.1_1756814004887_0.8347182546220335"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-02T11:20:52.759Z","modified":"2025-09-02T11:53:25.259Z","1.0.0":"2025-09-02T11:20:53.069Z","1.0.1":"2025-09-02T11:53:25.076Z"},"bugs":{"url":"https://github.com/beniwalsanjay/egenome-libs/issues"},"author":{"name":"sanjaybeniwal"},"license":"ISC","homepage":"https://github.com/beniwalsanjay/egenome-libs#readme","keywords":["typescript","library","solid","template"],"repository":{"type":"git","url":"git+https://github.com/beniwalsanjay/egenome-libs.git"},"description":"A scalable TypeScript library for eGenome.","maintainers":[{"name":"sanjaybeniwal","email":"beniwal1511@gmail.com"}],"readme":"# @beniwalsanjay/egenome-libs\n\nA comprehensive, production-ready TypeScript library for building scalable caching solutions with SOLID principles.\n\n## 🚀 Features\n\n- **🏗️ SOLID Architecture**: Clean, maintainable design following SOLID principles\n- **🔄 Multiple Store Implementations**: In-memory, Redis, multi-tier caching, enhanced memory with LRU eviction\n- **⏰ TTL Support**: Time-to-live functionality with automatic expiration\n- **📊 Advanced Statistics**: Detailed cache performance metrics\n- **🔧 Batch Operations**: Efficient multi-key operations\n- **🛡️ Robust Error Handling**: Comprehensive error types and handling\n- **🎯 Result Type**: Functional programming approach with Result<T, E>\n- **⚙️ Configuration Management**: Flexible, type-safe configuration system\n- **📝 Comprehensive Logging**: Built-in logging with custom logger support\n- **🧪 Extensively Tested**: 90%+ test coverage with comprehensive test suite\n- **📦 Tree-shakable**: Import only what you need\n- **🔍 TypeScript First**: Full TypeScript support with excellent IntelliSense\n\n## 📦 Installation\n\n```bash\nnpm install @beniwalsanjay/egenome-libs\n```\n\n### Optional Dependencies\n\nFor Redis support:\n```bash\nnpm install ioredis\nnpm install --save-dev @types/ioredis\n```\n\nFor Memcached support (if you implement MemcachedStore):\n```bash\nnpm install memcached\nnpm install --save-dev @types/memcached\n```\n\n## 🏃 Quick Start\n\n### Basic Cache Usage\n\n```typescript\nimport { InMemoryStore, simpleCacheItem } from '@beniwalsanjay/egenome-libs';\n\nconst store = new InMemoryStore<string>();\n\nconst result = await simpleCacheItem({\n  store,\n  key: 'user:123',\n  fetcher: async () => {\n    // Simulate API call\n    return 'User data from API';\n  }\n});\n\nif (result.ok) {\n  console.log(result.value); // \"User data from API\"\n}\n```\n\n### Enhanced Cache with TTL and Statistics\n\n```typescript\nimport { EnhancedMemoryStore, cacheItem } from '@beniwalsanjay/egenome-libs';\n\nconst store = new EnhancedMemoryStore<UserData>();\n\nconst result = await cacheItem({\n  store,\n  key: 'user:123',\n  fetcher: async () => fetchUserFromAPI('123'),\n  options: {\n    ttlMs: 5 * 60 * 1000, // 5 minutes\n    maxRetries: 3,\n    retryDelayMs: 1000\n  }\n});\n\nif (result.ok) {\n  console.log(`Value: ${result.value.value}`);\n  console.log(`From cache: ${result.value.fromCache}`);\n  console.log(`Operation took: ${result.value.metadata.operationTimeMs}ms`);\n}\n\n// Get cache statistics\nconst stats = await store.getStats();\nif (stats.ok) {\n  console.log(`Hit ratio: ${stats.value.hitRatio}`);\n  console.log(`Total keys: ${stats.value.keyCount}`);\n}\n```\n\n### Namespaced Store\n\n```typescript\nimport { InMemoryStore, NamespacedStore } from '@beniwalsanjay/egenome-libs';\n\nconst baseStore = new InMemoryStore();\nconst userCache = new NamespacedStore(baseStore, 'users');\nconst productCache = new NamespacedStore(baseStore, 'products');\n\n// Keys are automatically prefixed\nawait userCache.set('123', { name: 'John' });\nawait productCache.set('123', { title: 'Widget' });\n\n// No key conflicts - they're stored as 'users:123' and 'products:123'\n```\n\n### Redis Cache\n\n```typescript\nimport { RedisStore, cacheItem } from '@beniwalsanjay/egenome-libs';\n\nconst redisStore = new RedisStore<UserData>({\n  host: 'localhost',\n  port: 6379,\n  password: 'your-password',\n  db: 0\n});\n\nconst result = await cacheItem({\n  store: redisStore,\n  key: 'user:123',\n  fetcher: async () => fetchUserFromDatabase('123'),\n  options: {\n    ttlMs: 10 * 60 * 1000, // 10 minutes\n    maxRetries: 3\n  }\n});\n```\n\n### Multi-Tier Cache (Memory + Redis)\n\n```typescript\nimport { \n  EnhancedMemoryStore, \n  RedisStore, \n  MultiTierStore,\n  cacheItem \n} from '@beniwalsanjay/egenome-libs';\n\n// L1: Fast memory cache\nconst l1Cache = new EnhancedMemoryStore<UserData>();\n\n// L2: Persistent Redis cache  \nconst l2Cache = new RedisStore<UserData>({\n  host: 'localhost',\n  port: 6379\n});\n\n// Multi-tier with read-through and write-through\nconst multiTierCache = new MultiTierStore(l1Cache, l2Cache, {\n  l1TtlMs: 2 * 60 * 1000,      // L1: 2 minutes (fast access)\n  l2TtlMs: 30 * 60 * 1000,     // L2: 30 minutes (persistence)\n  populateL1OnL2Hit: true,     // Promote L2 hits to L1\n  writeThrough: true           // Write to both tiers\n});\n\nconst result = await cacheItem({\n  store: multiTierCache,\n  key: 'user:123',\n  fetcher: async () => expensiveOperation('123')\n});\n\n// First call: Fetches data, stores in both L1 and L2\n// Second call: Sub-millisecond response from L1\n// L1 eviction: Still fast response from L2, re-populates L1\n```\n\n## 📚 Core Concepts\n\n### Result Type\n\nAll operations return a `Result<T, E>` type for functional error handling:\n\n```typescript\nimport { Ok, Err, ResultUtils } from '@beniwalsanjay/egenome-libs';\n\nconst result = await store.get('key');\n\nif (result.ok) {\n  // Type-safe access to value\n  console.log(result.value);\n} else {\n  // Handle error\n  console.error(result.error);\n}\n\n// Functional programming patterns\nconst doubled = ResultUtils.map(result, x => x * 2);\nconst combined = ResultUtils.all([result1, result2, result3]);\n```\n\n### Error Handling\n\nComprehensive error types with context:\n\n```typescript\nimport { \n  isStoreError, \n  isCacheError, \n  StoreErrorCode,\n  CacheErrorCode \n} from '@beniwalsanjay/egenome-libs';\n\nconst result = await store.get('key');\nif (!result.ok) {\n  if (isStoreError(result.error)) {\n    if (result.error.code === StoreErrorCode.CONNECTION_FAILED) {\n      // Handle connection error\n    }\n  }\n}\n```\n\n### Configuration\n\nFlexible configuration system:\n\n```typescript\nimport { createConfig, EnhancedMemoryStore } from '@beniwalsanjay/egenome-libs';\n\nconst config = createConfig({\n  defaultTtlMs: 10 * 60 * 1000, // 10 minutes\n  debug: true,\n  stores: {\n    memory: {\n      maxMemoryBytes: 100 * 1024 * 1024, // 100MB\n      cleanupIntervalMs: 30 * 1000 // 30 seconds\n    }\n  }\n});\n\nconst store = new EnhancedMemoryStore(config.get('stores')?.memory);\n```\n\n## 🛠️ API Reference\n\n### Store Interfaces\n\n#### `IKeyValueStore<V>`\nCore interface for all stores:\n- `get(key, options?)` - Retrieve a value\n- `set(key, value, options?)` - Store a value\n- `has(key)` - Check if key exists\n- `delete(key)` - Remove a key\n- `clear()` - Remove all keys\n- `mget(keys, options?)` - Get multiple values\n- `mset(operations)` - Set multiple values\n- `keys(pattern?)` - List keys\n- `getStats()` - Get store statistics\n\n#### `IEvictableStore<V>`\nExtended interface for stores with eviction:\n- `evict(count?)` - Manually evict items\n- `getLruKeys(count)` - Get least recently used keys\n- `getLfuKeys(count)` - Get least frequently used keys\n\n### Store Implementations\n\n#### `InMemoryStore<V>`\nBasic in-memory implementation:\n```typescript\nconst store = new InMemoryStore<string>();\n```\n\n#### `EnhancedMemoryStore<V>`\nAdvanced in-memory store with TTL, LRU eviction, and statistics:\n```typescript\nconst store = new EnhancedMemoryStore<UserData>({\n  maxMemoryBytes: 50 * 1024 * 1024,\n  cleanupIntervalMs: 60 * 1000,\n  autoCleanup: true\n});\n```\n\n#### `NamespacedStore<V>`\nDecorator for adding namespaces:\n```typescript\nconst namespacedStore = new NamespacedStore(baseStore, 'namespace');\n```\n\n#### `RedisStore<V>`\nProduction-ready Redis implementation:\n```typescript\nconst redisStore = new RedisStore<UserData>({\n  host: 'localhost',\n  port: 6379,\n  password: 'secret',\n  db: 0,\n  connectTimeoutMs: 5000,\n  commandTimeoutMs: 3000\n});\n```\n\n#### `MultiTierStore<V>`\nMulti-tier cache combining memory and external storage:\n```typescript\nconst multiTierStore = new MultiTierStore(memoryCache, redisCache, {\n  l1TtlMs: 60 * 1000,\n  l2TtlMs: 600 * 1000,\n  writeThrough: true,\n  populateL1OnL2Hit: true\n});\n```\n\n### Cache Functions\n\n#### `cacheItem<V>(input)`\nAdvanced cache function with detailed results:\n```typescript\nconst result = await cacheItem({\n  store,\n  key: 'cache-key',\n  fetcher: async () => 'value',\n  options: {\n    ttlMs: 300000,\n    maxRetries: 3,\n    retryDelayMs: 1000,\n    defaultValue: 'fallback'\n  }\n});\n```\n\n#### `simpleCacheItem<V>(input)`\nSimplified cache function (backward compatible):\n```typescript\nconst result = await simpleCacheItem({\n  store,\n  key: 'cache-key',\n  fetcher: async () => 'value'\n});\n```\n\n#### `cacheWithInvalidation<V>(input)`\nCache with automatic invalidation:\n```typescript\nconst result = await cacheWithInvalidation({\n  store,\n  key: 'cache-key',\n  fetcher: async () => 'value',\n  invalidateAfterMs: 300000\n});\n```\n\n#### `cacheMultipleItems<V>(inputs)`\nBatch cache operations:\n```typescript\nconst results = await cacheMultipleItems([\n  { store, key: 'key1', fetcher: () => 'value1' },\n  { store, key: 'key2', fetcher: () => 'value2' }\n]);\n```\n\n## 🧪 Testing\n\nRun the comprehensive test suite:\n\n```bash\nnpm test\n```\n\nRun tests in watch mode:\n\n```bash\nnpm run test:watch\n```\n\n## 📝 Examples\n\n### Real-world Usage Example\n\n```typescript\nimport { \n  EnhancedMemoryStore, \n  NamespacedStore, \n  cacheItem,\n  createConfig,\n  ConsoleLogger \n} from '@beniwalsanjay/egenome-libs';\n\n// Configure the library\nconst config = createConfig({\n  debug: true,\n  defaultTtlMs: 5 * 60 * 1000,\n  logger: new ConsoleLogger(true),\n  stores: {\n    memory: {\n      maxMemoryBytes: 100 * 1024 * 1024,\n      cleanupIntervalMs: 60 * 1000\n    }\n  }\n});\n\n// Create stores\nconst baseStore = new EnhancedMemoryStore(config.get('stores')?.memory);\nconst userStore = new NamespacedStore(baseStore, 'users');\nconst sessionStore = new NamespacedStore(baseStore, 'sessions');\n\n// Cache user data\nasync function getUser(id: string) {\n  return cacheItem({\n    store: userStore,\n    key: id,\n    fetcher: async () => {\n      const response = await fetch(`/api/users/${id}`);\n      return response.json();\n    },\n    options: {\n      ttlMs: 10 * 60 * 1000, // 10 minutes\n      maxRetries: 2,\n      retryDelayMs: 500\n    }\n  });\n}\n\n// Cache session data with shorter TTL\nasync function getSession(token: string) {\n  return cacheItem({\n    store: sessionStore,\n    key: token,\n    fetcher: async () => validateSessionToken(token),\n    options: {\n      ttlMs: 5 * 60 * 1000, // 5 minutes\n      refreshTtl: true // Refresh TTL on access\n    }\n  });\n}\n\n// Monitor cache performance\nsetInterval(async () => {\n  const stats = await baseStore.getStats();\n  if (stats.ok) {\n    console.log(`Cache stats:`, {\n      hitRatio: stats.value.hitRatio,\n      keyCount: stats.value.keyCount,\n      memoryUsage: `${Math.round(stats.value.memoryUsageBytes / 1024)}KB`\n    });\n  }\n}, 30000);\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin feature/my-new-feature`\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.\n\n## 🆕 Changelog\n\n### v1.0.0 (Latest)\n- ✨ Complete refactor with SOLID principles\n- ✨ Enhanced memory store with LRU eviction\n- ✨ TTL support with automatic expiration\n- ✨ **Redis integration** with production-ready features\n- ✨ **Multi-tier caching** (Memory + Redis/External)\n- ✨ **Advanced cache strategies** (read-through, write-through, write-behind)\n- ✨ Comprehensive error handling with custom error types\n- ✨ Result type for functional programming\n- ✨ Configuration management system\n- ✨ Advanced statistics and monitoring\n- ✨ Batch operations support\n- ✨ Namespaced store decorator\n- ✨ Multiple cache strategies\n- ✨ Extensive test coverage (90%+)\n- ✨ Complete TypeScript rewrite\n- ✨ Performance optimizations","readmeFilename":"README.md"}