@loipv/nestjs-cache 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## 1.0.0
+
+### Major Changes
+
+- First release on npm.
+
+  `@loipv/nestjs-cache` 1.0.0 is the first published version. The public API is frozen and follows
+  [semver](https://github.com/loipv/nestjs-cache/blob/main/docs/semver.md) from here.
+
+  - Requirements: Node 22 or later; TypeScript 5.4 or later with `experimentalDecorators`; peers `@nestjs/common` and `@nestjs/core` `^11.0.0 || ^12.0.0`, `rxjs` `^7.1.0`, `reflect-metadata` `^0.2.0`, and the optional `ioredis` `^5.0.0 || ^6.0.0` or `redis` `^5.0.0 || ^6.0.0`.
+  - `escapeKeyArgs` defaults to `false`: template arguments are not escaped unless you enable it, see [security](https://github.com/loipv/nestjs-cache/blob/main/docs/security.md).
+  - Decorators: `@Cacheable`, `@CachePut`, `@CacheEvict` and the `CacheService` API, see [decorators](https://github.com/loipv/nestjs-cache/blob/main/docs/decorators.md) and [the service](https://github.com/loipv/nestjs-cache/blob/main/docs/cache-service.md).
+  - Stores: memory, Redis (ioredis or node-redis v5/v6, Cluster, Sentinel) and tiered L1/L2 with invalidation, see [stores](https://github.com/loipv/nestjs-cache/blob/main/docs/stores.md).
+  - Resilience: distributed locks, circuit breaker, `swr` and `sliding` strategies, `softTimeout`, see [resilience](https://github.com/loipv/nestjs-cache/blob/main/docs/resilience.md).
+  - Namespaces and tags: versioned namespaces with O(1) `clear`, batch API, tag invalidation, see [namespaces and tags](https://github.com/loipv/nestjs-cache/blob/main/docs/namespaces-and-tags.md).
+  - HTTP caching: `@HttpCache` on Express and Fastify, see [HTTP caching](https://github.com/loipv/nestjs-cache/blob/main/docs/http-caching.md).
+  - Serializers and compression: JSON serializer and gzip or brotli `compressedSerializer` (with a `level` option; brotli defaults to quality 4), see [serializers](https://github.com/loipv/nestjs-cache/blob/main/docs/serializers.md).
+  - Observability: Prometheus metrics, `@nestjs/terminus` health indicator and OpenTelemetry tracing, see [observability](https://github.com/loipv/nestjs-cache/blob/main/docs/observability.md).
+  - Security and migration: see [security](https://github.com/loipv/nestjs-cache/blob/main/docs/security.md) and [migrating from `@nestjs/cache-manager`](https://github.com/loipv/nestjs-cache/blob/main/docs/migration-from-cache-manager.md).
+
+Versions 0.1.0 to 0.3.0 below were never published to npm.
+
+## [0.3.0] - 2026-11-10
+
+### Added
+
+- `CachePrometheusModule` (`forRoot` and `forRootAsync`) that records cache metrics through a Prometheus client you pass in (`@prometheus-io/client` or `prom-client`), with the `PrometheusClientLike`, `RegistryLike` and `CachePrometheusOptions` types.
+- `CacheHealthIndicator` and `CacheHealthResult`, a health check in the shape `@nestjs/terminus` expects.
+- `CacheStore.ping` (optional), implemented by the memory, Redis, tiered and circuit breaker stores.
+- `logging.level` (`'off'`, `'error'` or `'debug'`) and the `CacheLogLevel` type.
+- Log lines when a circuit breaker opens (`warn`) or closes (`log`).
+- Sample Grafana dashboard in `grafana/dashboard.json` (in the repository, not in the npm package).
+
+### Changed
+
+- Metrics and health ship from the main entry point, not from the `/prometheus` and `/terminus` subpaths planned earlier. The CommonJS build would otherwise bundle a second copy of the `CacheEvents` class into each entry point, and the metrics collector and the module would then use different classes.
+- Prometheus clients are passed in by the user; there is no new peer dependency.
+- `IoredisLike` gained a required `ping()`. Real ioredis clients are unaffected, but hand-written stubs must add it.
+- `CacheEventSink` gained an optional `logLevel` field. This is additive.
+- `CacheOperation` gained the value `'metrics'`, used for logs only; `error` events never carry it.
+
+## [0.2.0] - 2026-11-10
+
+### Added
+
+- Expiry strategies `fixed`, `swr` (stale-while-revalidate, with `staleTtl`) and `sliding` (with optional `maxTtl`) for `@Cacheable`, `@CachePut`, `CacheService.getOrSet`, `CacheService.set` and `CacheService.get`.
+- Optional distributed lock (`defaults.lock`, per-call `lock`) that coalesces concurrent misses across instances; `LockProvider`, `LockHandle` and `CacheStore.lock`, implemented by the Redis store and by a tiered store whose L2 has a lock.
+- `circuitBreaker(store, options)`, `CircuitBreakerStore`, `CircuitOpenError` and the `CircuitBreakerOptions` and `BreakerState` types.
+- `lock` and `breaker` events; `hit.stale` is `true` for `swr` stale reads.
+- `getAndTouch` (already optional on `CacheStore` and implemented by `RedisStore` in 0.1) is now also implemented by the memory and tiered stores.
+- `MemoryStoreOptions` type export; `CacheLockDefaults` type export.
+
+### Changed
+
+- `WriteOptions` is now a type alias containing a union, so `interface X extends WriteOptions` no longer compiles; use `type X = WriteOptions & { ... }`.
+- `IoredisLike` gained a required `eval` and a `set ... 'NX'` overload. Real ioredis clients are unaffected, but hand-written fakes must add them.
+- Repeated `error` log lines are throttled to one per 30 seconds for each (store, operation) pair, with a `(+N similar errors suppressed)` suffix. Events are still emitted for every occurrence.
+- `package.json` now has `repository`, `homepage`, `bugs` and more keywords.
+- `defaults.lock` must be an object: `null`, a string, a number, a boolean or an array throws `CacheConfigError` (`undefined` still means the defaults).
+
+### Fixed
+
+- Decorators on `static` methods are rejected with `CacheConfigError`.
+- `@CacheEvict({ key: [] })` is rejected with `CacheConfigError`.
+- Lock-unavailable warnings are de-duplicated once per class, method and store, so a method that names two stores without a lock warns for each.
+
+## [0.1.0] - 2026-11-10
+
+### Added
+
+- `@Cacheable`, `@CachePut` and `@CacheEvict` decorators and a `CacheService` for direct calls.
+- Named stores: in-memory LRU, Redis (ioredis) and a two-tier L1/L2 store with Pub/Sub invalidation.
+- In-process coalescing of concurrent misses, optional null caching and TTL jitter.
+- Dynamic keys from templates or callbacks, a `CacheEvents` emitter, and a pluggable serializer.
+- Dual ESM and CommonJS build with no runtime dependencies.
+
+[0.3.0]: https://github.com/loipv/nestjs-cache/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/loipv/nestjs-cache/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/loipv/nestjs-cache/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loipv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @loipv/nestjs-cache
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Decorator-based caching for NestJS: Redis (ioredis or node-redis, Cluster, Sentinel) and two-tier stores, tags, stale-while-revalidate, stampede protection, HTTP caching and Prometheus metrics
+
+- `@Cacheable`, `@CachePut` and `@CacheEvict` decorators, plus a `CacheService` for direct calls.
+- `@HttpCache` for opt-in caching of controller routes (Express and Fastify).
+- Named stores: in-memory, Redis (ioredis or node-redis, standalone, Cluster or Sentinel) and a two-tier L1/L2 store synced over Pub/Sub.
+- Concurrent misses on the same key are coalesced into one load (per process), or across instances with the optional distributed lock.
+- Expiry strategies: `fixed`, `swr` (stale-while-revalidate) and `sliding`.
+- Per-store circuit breaker for Redis outages.
+- Optional gzip or brotli compression of large payloads (`compressedSerializer`).
+- Optional null caching and TTL jitter, both off by default.
+- No runtime dependencies. Dual ESM and CommonJS build.
+
+## Install
+
+```bash
+npm install @loipv/nestjs-cache
+```
+
+Peer dependencies: `@nestjs/common`, `@nestjs/core` (`^11 || ^12`), `reflect-metadata` (`^0.2`) and `rxjs` (`^7.1`, which
+Nest itself requires, so a Nest app already has it).
+`ioredis` (`^5 || ^6`) and `redis` (`^5 || ^6`, node-redis) are optional peers; install the one you use for the Redis store.
+
+## Quick start
+
+With no options the module uses an in-memory store named `default`. No Redis is needed.
+
+```ts
+import { Injectable, Module } from '@nestjs/common';
+import { CacheModule, Cacheable } from '@loipv/nestjs-cache';
+
+@Injectable()
+export class UserService {
+  @Cacheable({ namespace: 'users', key: 'user:{0}', ttl: 60_000 })
+  async findById(id: string): Promise<{ id: string } | null> {
+    return { id }; // for example, a database call
+  }
+}
+
+@Module({
+  imports: [CacheModule.forRoot({ isGlobal: true })],
+  providers: [UserService],
+})
+export class AppModule {}
+```
+
+With memory only, the cache is private to each process: it is not shared between instances and is lost on restart.
+All durations are in milliseconds and must be finite numbers greater than 0.
+
+For Redis, Redis Cluster or Sentinel and the two-tier store, see [Stores](docs/stores.md). A runnable NestJS 12 app
+with tags, `@HttpCache`, optional Redis and Prometheus is in [`examples/basic`](examples/basic/README.md).
+
+## Documentation
+
+- [Configuration](docs/configuration.md): module options and defaults, null caching, TTL jitter and the expiry
+  strategies (`fixed`, `swr` with `softTimeout`, `sliding`).
+- [Decorators](docs/decorators.md): `@Cacheable`, `@CachePut` and `@CacheEvict`, their options, and dynamic keys.
+- [HTTP caching](docs/http-caching.md): `@HttpCache` on controller routes, on Express and Fastify.
+- [`CacheService`](docs/cache-service.md): `get`, `set`, `delete`, `clear`, `getOrSet` and the batch methods
+  `getMany`, `setMany` and `getOrSetMany`.
+- [Stores](docs/stores.md): memory, Redis (ioredis or node-redis; standalone, Cluster or Sentinel), the two-tier
+  store, custom stores and invalidation buses.
+- [Versioned namespaces and tags](docs/namespaces-and-tags.md): an O(1) namespace `clear`, and tag invalidation with
+  `invalidateTags` and `@CacheEvict({ tags })`.
+- [Serializers](docs/serializers.md): custom serializers and gzip or brotli compression (`compressedSerializer`).
+- [Resilience](docs/resilience.md): the distributed lock, the circuit breaker, and how errors are handled.
+- [Events and observability](docs/observability.md): events, Prometheus metrics, the `@nestjs/terminus` health check,
+  logging and a sample Grafana dashboard.
+- [Tracing](docs/observability.md#tracing): opt-in OpenTelemetry spans for every cache call, with `CacheTracingModule`.
+- [Security](docs/security.md) and [Caveats](docs/caveats.md).
+- [Stability and semver](docs/semver.md): what 1.x keeps stable, and what counts as a major, minor or patch change.
+- [Migrating from `@nestjs/cache-manager`](docs/migration-from-cache-manager.md).
+
+## Compatibility
+
+The semver contract is in [Stability and semver](docs/semver.md).
+
+| Component          | Supported                                                  |
+| ------------------ | ---------------------------------------------------------- |
+| NestJS             | 11 (CommonJS) and 12 (ESM)                                 |
+| Node.js            | `>=22` (LTS 22, 24, 26)                                    |
+| TypeScript         | `>=5.4` (the published `.d.ts` is checked against 5.4)     |
+| ioredis            | `^5 \|\| ^6` (optional peer; Cluster needs 5.6.0 or later) |
+| redis (node-redis) | `^5 \|\| ^6` (optional peer; Sentinel supported)           |
+| rxjs               | `^7.1` (peer, as for `@nestjs/common`)                     |
+| Redis server       | 6.2 or later (Cluster: 7 or later)                         |
+
+The decorators (`@Cacheable`, `@CachePut`, `@CacheEvict`, `@HttpCache`) are legacy decorators: consumers need
+`experimentalDecorators: true` in `tsconfig.json`. Standard (TC39) decorators are not supported.
+
+The package ships both ESM and CommonJS builds. The injection tokens use `Symbol.for('@loipv/nestjs-cache:...')`,
+so they are shared when both builds are loaded in one process, and `instanceof CacheConfigError` matches errors
+from either build. Classes are not shared: `CacheService`, `CacheEvents` and the other classes are injected by
+class, so import the package from one build only (do not mix `import` and `require` of it in one app).
+The library does not rely on `emitDecoratorMetadata`.
+
+## Roadmap
+
+- **0.2 - Resilience (done):** distributed lock (cross-instance stampede protection), per-store circuit breaker, `'swr'` (stale-while-revalidate) and `'sliding'` TTL strategies.
+- **0.3 - Observability (done):** Prometheus metrics (`CachePrometheusModule`) with a sample Grafana dashboard, configurable log level with debug logs, circuit breaker logs, and a `@nestjs/terminus` health indicator (`CacheHealthIndicator`). All from the main entry point.
+- **0.4 - Versioned namespaces and batches (done):** O(1) `clear` for opt-in versioned namespaces, `getMany`/`setMany`/`getOrSetMany`, `escapeKeyArgs`, lock keys under the prefix, and an optional `ping`.
+- **0.5 - Redis Cluster and node-redis (done):** Redis Cluster through ioredis, `nodeRedisAdapter` for `redis` v5 (standalone and cluster), `CacheStore.getStrict`/`setStrict`, `RedisClientAdapter.scanIterator`, and the tiered-store fix for versioned namespaces while L2 is down.
+- **0.6 - HTTP caching (done):** `@HttpCache` and `HttpCacheInterceptor` for opt-in route caching on Express and Fastify, and a [migration guide](docs/migration-from-cache-manager.md) from `@nestjs/cache-manager`.
+- **0.7 - Tags (done):** `tags` on `@Cacheable`, `@CachePut`, `@HttpCache` and the `CacheService` writes, `CacheService.invalidateTags` and `@CacheEvict({ tags })`.
+- **0.8 - Compression, Sentinel and `softTimeout` (done):** `compressedSerializer` (gzip and brotli), swr `softTimeout`, Redis Sentinel (ioredis and node-redis), and the tag token re-read.
+- **0.9 - Redis v6, docs and example (done):** `redis` v6 support, the docs split into `docs/`, an [example app](examples/basic/README.md), and an API tidy-up (see the changelog for the breaking changes).
+- **0.10 - Tracing (done):** opt-in OpenTelemetry tracing (`CacheTracingModule`).
+- **1.0 - API freeze (done):** the public API is frozen and follows [semver](docs/semver.md) from there.
+- **After 1.0 - Replica reads (planned):** reads from Redis replicas.
+
+## Changelog and releasing
+
+Each version's changes are listed in [CHANGELOG.md](CHANGELOG.md). [RELEASING.md](RELEASING.md) describes how
+releases are published and the rules the CI workflows follow.
+
+## License
+
+MIT