{"_id":"@node-ts-cache/core","_rev":"3-8fa0680c4c90795ae7aed63926092c4b","name":"@node-ts-cache/core","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@node-ts-cache/core","version":"1.0.0","keywords":["node","nodejs","cache","typescript","ts","caching","memcache","memory-cache","redis-cache","redis","file-cache","node-cache","ts-cache"],"author":{"name":"Simon Tretter","email":"s.tretter@gmail.com"},"license":"MIT","_id":"@node-ts-cache/core@1.0.0","maintainers":[{"name":"simllll","email":"s.tretter@gmail.com"}],"contributors":[{"name":"Himmet Avsar","email":"avsar.himmet1@gmail.com"}],"homepage":"https://github.com/simllll/node-ts-cache/tree/master/ts-cache#readme","bugs":{"url":"https://github.com/simllll/node-ts-cache/issues"},"dist":{"shasum":"cd1ab2431457c98d12ca9b616a63860db5f02996","tarball":"https://registry.npmjs.org/@node-ts-cache/core/-/core-1.0.0.tgz","fileCount":42,"integrity":"sha512-yzJzLUk1Exk6KqnATn9LjVno11EiJBI91kvxSStTSecmrSfd6yhNOkv+1r0AuOkre0OMav+yAtPGVch3/licbA==","signatures":[{"sig":"MEUCICciXWrZQ3riHHIoxuLz+xht/CuRVzCIONWcJ/b4rMUMAiEAsNqTjWF0aecXRPm89gIaLJhxJ2tPOE5jkhvKzMtXvpQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":57246},"main":"dist/index.js","type":"module","_from":"file:node-ts-cache-core-1.0.0.tgz","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"c938eba762060f940a34bc192bec03bc76ea4017","scripts":{"dev":"tsc -p . -w","tdd":"mocha --loader=ts-node/esm -w","test":"mocha --loader=ts-node/esm test/**/*.test.ts","build":"tsc -p .","clean":"git clean -fdx src","tdd-debug-brk":"mocha --loader=ts-node/esm --inspect-brk"},"_npmUser":{"name":"simllll","email":"s.tretter@gmail.com"},"_resolved":"/tmp/575418e946b3c93f3fbd11d068b00276/node-ts-cache-core-1.0.0.tgz","_integrity":"sha512-yzJzLUk1Exk6KqnATn9LjVno11EiJBI91kvxSStTSecmrSfd6yhNOkv+1r0AuOkre0OMav+yAtPGVch3/licbA==","repository":{"url":"git+https://github.com/simllll/node-ts-cache.git","type":"git"},"_npmVersion":"11.7.0","description":"Simple and extensible caching module supporting decorators","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ioredis":"^5.3.2","ioredis-mock":"^8.9.0"},"_npmOperationalInternal":{"tmp":"tmp/core_1.0.0_1769032341172_0.3259555095432505","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@node-ts-cache/core","version":"1.0.1","keywords":["node","nodejs","cache","typescript","ts","caching","memcache","memory-cache","redis-cache","redis","file-cache","node-cache","ts-cache"],"author":{"name":"Simon Tretter","email":"s.tretter@gmail.com"},"license":"MIT","_id":"@node-ts-cache/core@1.0.1","maintainers":[{"name":"simllll","email":"s.tretter@gmail.com"}],"contributors":[{"name":"Himmet Avsar","email":"avsar.himmet1@gmail.com"}],"homepage":"https://github.com/simllll/node-ts-cache/tree/master/ts-cache#readme","bugs":{"url":"https://github.com/simllll/node-ts-cache/issues"},"dist":{"shasum":"20e1f4500c9e9c735970007db64ef0d88e217505","tarball":"https://registry.npmjs.org/@node-ts-cache/core/-/core-1.0.1.tgz","fileCount":42,"integrity":"sha512-iv1qpQNPF+1eDPDeW8kiNxkjegGeZdLVh2pR7pe5ANSi5I1QUONqNMVe+rSj+x4sfxGoBJVMTN/KtsqjLlKzNw==","signatures":[{"sig":"MEQCICDt1VcaSMsACSW6zo9O0zc5feWb91mvCBjZxAQIxzqjAiBp8PwE+LMxEd+HPQw64i9zSIX3jJ+dG9dj8R8OOS42NQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@node-ts-cache%2fcore@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":42231},"type":"module","_from":"file:node-ts-cache-core-1.0.1.tgz","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c938eba762060f940a34bc192bec03bc76ea4017","scripts":{"dev":"tsc -p . -w","test":"vitest run","build":"tsc -p .","clean":"git clean -fdx src"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f15db919-f257-4fa2-8a67-42eb1a364b0d"}},"_resolved":"/tmp/8c8b97c3518002892ad585efae6a27e4/node-ts-cache-core-1.0.1.tgz","_integrity":"sha512-iv1qpQNPF+1eDPDeW8kiNxkjegGeZdLVh2pR7pe5ANSi5I1QUONqNMVe+rSj+x4sfxGoBJVMTN/KtsqjLlKzNw==","repository":{"url":"git+https://github.com/simllll/node-ts-cache.git","type":"git"},"_npmVersion":"11.6.2","description":"Simple and extensible caching module supporting decorators","directories":{},"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ioredis":"^5.3.2","ioredis-mock":"^8.9.0"},"_npmOperationalInternal":{"tmp":"tmp/core_1.0.1_1769082682640_0.7372283759453493","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@node-ts-cache/core","version":"1.0.2","description":"Simple and extensible caching module supporting decorators","keywords":["node","nodejs","cache","typescript","ts","caching","memcache","memory-cache","redis-cache","redis","file-cache","node-cache","ts-cache"],"homepage":"https://github.com/simllll/node-ts-cache/tree/master/ts-cache#readme","bugs":{"url":"https://github.com/simllll/node-ts-cache/issues"},"repository":{"type":"git","url":"git+https://github.com/simllll/node-ts-cache.git"},"license":"MIT","author":{"name":"Simon Tretter","email":"s.tretter@gmail.com"},"contributors":[{"name":"Himmet Avsar","email":"avsar.himmet1@gmail.com"}],"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"devDependencies":{"ioredis":"^5.3.2","ioredis-mock":"^8.9.0"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"gitHead":"c938eba762060f940a34bc192bec03bc76ea4017","scripts":{"build":"tsc -p .","clean":"git clean -fdx src","dev":"tsc -p . -w","test":"vitest run"},"_id":"@node-ts-cache/core@1.0.2","_integrity":"sha512-5r1gkB988G/SIfovPlzinUHJOA76qGE7TWrpFImH/I6zqXUl2R8yiA6agWf+P6CdGrgw9LelrYfy7FyHgT4zsQ==","_resolved":"/tmp/5f4e1d5b5e682c31e95acec9f498dd71/node-ts-cache-core-1.0.2.tgz","_from":"file:node-ts-cache-core-1.0.2.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-5r1gkB988G/SIfovPlzinUHJOA76qGE7TWrpFImH/I6zqXUl2R8yiA6agWf+P6CdGrgw9LelrYfy7FyHgT4zsQ==","shasum":"6eb99be6ad795003b055601da9595c6a37120d8b","tarball":"https://registry.npmjs.org/@node-ts-cache/core/-/core-1.0.2.tgz","fileCount":42,"unpackedSize":42901,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@node-ts-cache%2fcore@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQChtYRm5tOb1jxpH79UQgzNIvlu6aEExdr2N6ON2+X4yAIgY7qt5aQ7eWOBihaZEDhD+2Jw2bvgvCbYVCMrG9sQ1/U="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f15db919-f257-4fa2-8a67-42eb1a364b0d"}},"directories":{},"maintainers":[{"name":"simllll","email":"s.tretter@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_1.0.2_1769158101118_0.5627474790992593"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-21T21:52:21.114Z","modified":"2026-01-23T08:48:21.840Z","1.0.0":"2026-01-21T21:52:21.322Z","1.0.1":"2026-01-22T11:51:22.782Z","1.0.2":"2026-01-23T08:48:21.261Z"},"bugs":{"url":"https://github.com/simllll/node-ts-cache/issues"},"author":{"name":"Simon Tretter","email":"s.tretter@gmail.com"},"license":"MIT","homepage":"https://github.com/simllll/node-ts-cache/tree/master/ts-cache#readme","keywords":["node","nodejs","cache","typescript","ts","caching","memcache","memory-cache","redis-cache","redis","file-cache","node-cache","ts-cache"],"repository":{"type":"git","url":"git+https://github.com/simllll/node-ts-cache.git"},"description":"Simple and extensible caching module supporting decorators","contributors":[{"name":"Himmet Avsar","email":"avsar.himmet1@gmail.com"}],"maintainers":[{"name":"simllll","email":"s.tretter@gmail.com"}],"readme":"# @node-ts-cache/core\n\n[![npm](https://img.shields.io/npm/v/@node-ts-cache/core.svg)](https://www.npmjs.org/package/@node-ts-cache/core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js CI](https://github.com/simllll/node-ts-cache/actions/workflows/test.yml/badge.svg)](https://github.com/simllll/node-ts-cache/actions/workflows/test.yml)\n\nSimple and extensible caching module for TypeScript/Node.js with decorator support.\n\n## Installation\n\n```bash\nnpm install @node-ts-cache/core\n```\n\n## Quick Start\n\n```typescript\nimport { Cache, ExpirationStrategy, MemoryStorage } from '@node-ts-cache/core';\n\nconst cacheStrategy = new ExpirationStrategy(new MemoryStorage());\n\nclass UserService {\n\t@Cache(cacheStrategy, { ttl: 60 })\n\tasync getUser(id: string): Promise<User> {\n\t\treturn await database.findUser(id);\n\t}\n}\n```\n\n## Storage Engines\n\nThe core package includes `MemoryStorage` and `FsJsonStorage`. Additional storage backends are available as separate packages:\n\n| Package                                | Storage Type                                                          | Sync/Async | Use Case                               |\n| -------------------------------------- | --------------------------------------------------------------------- | ---------- | -------------------------------------- |\n| `@node-ts-cache/core`                  | MemoryStorage                                                         | Sync       | Development, simple caching            |\n| `@node-ts-cache/core`                  | FsJsonStorage                                                         | Async      | Persistent local cache                 |\n| `@node-ts-cache/node-cache-storage`    | [node-cache](https://www.npmjs.com/package/node-cache)                | Sync       | Production single-instance with TTL    |\n| `@node-ts-cache/lru-storage`           | [lru-cache](https://www.npmjs.com/package/lru-cache)                  | Sync       | Memory-bounded with automatic eviction |\n| `@node-ts-cache/redis-storage`         | [redis](https://www.npmjs.com/package/redis) (v4.x)                   | Async      | Shared cache                           |\n| `@node-ts-cache/ioredis-storage`       | [ioredis](https://www.npmjs.com/package/ioredis)                      | Async      | Shared cache with compression          |\n| `@node-ts-cache/lru-redis-storage`     | LRU + Redis                                                           | Async      | Two-tier: fast local + shared remote   |\n| `@node-ts-cache/elasticsearch-storage` | [elasticsearch](https://www.npmjs.com/package/@elastic/elasticsearch) | Async      | Search-integrated caching              |\n| `@node-ts-cache/memcached-storage`     | [memcached](https://www.npmjs.com/package/memcached)                  | Async      | High-performance distributed cache     |\n| `@node-ts-cache/valkey-storage`        | [iovalkey](https://www.npmjs.com/package/iovalkey)                    | Async      | Redis-compatible, open source          |\n\n## Decorators\n\n### @Cache\n\nCaches async method results. Cache key is generated from class name, method name, and arguments.\n\n```typescript\nclass ProductService {\n\t@Cache(strategy, { ttl: 300 })\n\tasync getProduct(id: string): Promise<Product> {\n\t\treturn await db.products.findById(id);\n\t}\n}\n```\n\n**Note:** `@Cache` always returns a Promise since cache operations may be asynchronous.\n\n### @SyncCache\n\nCaches synchronous method results without converting to Promises. Use with synchronous storages like `MemoryStorage` or `LRUStorage`.\n\n```typescript\nclass ConfigService {\n\t@SyncCache(strategy, { ttl: 60 })\n\tgetConfig(key: string): ConfigValue {\n\t\treturn computeConfig(key);\n\t}\n}\n```\n\n### @MultiCache\n\nMulti-tier caching with batch operations for array-based lookups.\n\n```typescript\nclass UserService {\n\t@MultiCache([localCache, redisCache], 0, id => `user:${id}`, { ttl: 300 })\n\tasync getUsersByIds(userIds: string[]): Promise<User[]> {\n\t\treturn await db.users.findByIds(userIds);\n\t}\n}\n```\n\n## Direct API Usage\n\nUse the caching strategy directly without decorators:\n\n```typescript\nconst cache = new ExpirationStrategy(new MemoryStorage());\n\n// Get item\nconst value = await cache.getItem<Data>('key');\n\n// Set item with TTL\nawait cache.setItem('key', data, { ttl: 300 });\n\n// Delete item\nawait cache.setItem('key', undefined);\n\n// Clear all\nawait cache.clear();\n```\n\n## ExpirationStrategy Options\n\n| Option            | Type      | Default | Description                                                                       |\n| ----------------- | --------- | ------- | --------------------------------------------------------------------------------- |\n| `ttl`             | `number`  | `60`    | Time to live in seconds                                                           |\n| `isLazy`          | `boolean` | `true`  | If `true`, delete on access after expiration. If `false`, delete via `setTimeout` |\n| `isCachedForever` | `boolean` | `false` | If `true`, items never expire                                                     |\n\n```typescript\n// Cache for 5 minutes with lazy expiration\nawait strategy.setItem('key', value, { ttl: 300, isLazy: true });\n\n// Cache forever\nawait strategy.setItem('key', value, { isCachedForever: true });\n\n// Cache with eager expiration (auto-delete after TTL)\nawait strategy.setItem('key', value, { ttl: 10, isLazy: false });\n```\n\n## Custom Key Strategies\n\nOverride default key generation by implementing `ISyncKeyStrategy` or `IAsyncKeyStrategy`:\n\n```typescript\nclass CustomKeyStrategy implements ISyncKeyStrategy {\n\tgetKey(className: string, methodName: string, args: any[]): string | undefined {\n\t\tif (args[0] === 'skip') return undefined; // Skip caching\n\t\treturn `${className}::${methodName}::${args.join('-')}`;\n\t}\n}\n\nclass MyService {\n\t@Cache(strategy, { ttl: 60 }, new CustomKeyStrategy())\n\tasync getData(id: string): Promise<Data> {\n\t\treturn fetchData(id);\n\t}\n}\n```\n\n## Advanced Features\n\n### Call Deduplication\n\nConcurrent calls with the same cache key share the same pending promise:\n\n```typescript\n// All three calls share one database request\nconst [a, b, c] = await Promise.all([\n\tservice.fetchData('123'),\n\tservice.fetchData('123'),\n\tservice.fetchData('123')\n]);\n```\n\n### Null vs Undefined\n\n- `undefined`: Cache miss or skip caching\n- `null`: Cached value (e.g., \"not found\" result)\n\n```typescript\nasync findUser(id: string): Promise<User | null> {\n  const user = await db.findUser(id);\n  return user ?? null; // Cache \"not found\" as null\n}\n```\n\n## Environment Variables\n\n| Variable                  | Description                                         |\n| ------------------------- | --------------------------------------------------- |\n| `DISABLE_CACHE_DECORATOR` | Set to any value to disable all `@Cache` decorators |\n\n## More Documentation\n\nSee [ADVANCED.md](./ADVANCED.md) for:\n\n- Interface definitions for implementing custom storages\n- Detailed storage configuration examples\n- @MultiCache in-depth usage\n- Error handling patterns\n\n## License\n\nMIT License\n","readmeFilename":"README.md"}