@warlock.js/cache 5.29.0 → 5.31.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `@warlock.js/cache` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.31.0 - 2026-10-18
+
+### Added
+
+- Real Redis integration coverage for atomic counters and their expiry behavior, including concurrent requests, preserved deadlines and counters recreated after a seeded key expires. Local runs opt in with `WARLOCK_REDIS_INTEGRATION=1`; CI requires a live Redis service. Tests use UUID prefixes and clean only their own keys.
+
+### Fixed
+
+- `cache.increment(key, amount, { ttl })` supplies a TTL when an atomic increment creates or recreates a counter, through direct, tagged and scoped calls. Existing expiry deadlines are preserved; an explicit TTL also repairs a live permanent counter across drivers. Redis applies the count and TTL together, so an expired seed cannot leave a permanent counter even when the driver has no default TTL.
+
+## 5.30.0 - 2026-10-16
+
+### Changed
+
+- Email addresses inside logged cache keys are masked (`user.member@example.com` logs as `u***@example.com`), in the base driver's operation log, in error lines (written even with logging off: SWR refresh failures, lock release, clone failures), in the "Cannot increment non-numeric value" error, and in the null driver.
+
+### Fixed
+
+- **`redis` driver `increment()` works on Redis 6.** With a default `ttl` configured it ran `EXPIRE … NX`, which only Redis 7+ accepts: on Redis 6 the call threw after the count had already gone up, which silently disabled login throttles and the cache-backed rate limiter. The increment and the default TTL are now applied together by one Lua script, and a TTL the counter already has is never shortened.
+- The default `increment()` (file and null drivers) reads a counter's value and deadline in one read. A counter that expired between two separate reads used to be rewritten from its stale value with no expiry at all, and every increment rounded the remaining TTL up, pushing the deadline up to a second later each time.
+- `file` driver: an entry stored without a TTL (its `expiresAt` is written to JSON as `null`) was read back by the internal entry reader as already expired, so `swr()` freshness checks and TTL-preserving writes treated it as missing.
+
 ## 5.29.0 - 2026-10-01
 
 ### Changed
@@ -75,6 +97,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Breaking
@@ -118,14 +141,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **Atomic `increment`/`decrement`, `pull` and `update`**, with a per-driver guarantee:
 
-  | Driver | `increment` / `decrement` | `pull` | `update` |
-  | --- | --- | --- | --- |
-  | `redis` | cross-server (`INCRBY`, keeps TTL) | cross-server (`GETDEL`, Lua fallback) | cross-server (Lua compare-and-set, bounded retries, `KEEPTTL`) |
-  | `pg` | cross-server (one upsert, keeps `expires_at`) | cross-server (`DELETE … RETURNING`) | cross-server (compare-and-set, bounded retries) |
-  | `memory` / `memoryExtended` / `lru` / `mock` | in-process, synchronous | in-process, synchronous | serialized per key, in-process only |
-  | `file` | serialized per key, in-process only | serialized per key, in-process only | not supported (throws) |
+  | Driver                                       | `increment` / `decrement`                     | `pull`                                | `update`                                                       |
+  | -------------------------------------------- | --------------------------------------------- | ------------------------------------- | -------------------------------------------------------------- |
+  | `redis`                                      | cross-server (`INCRBY`, keeps TTL)            | cross-server (`GETDEL`, Lua fallback) | cross-server (Lua compare-and-set, bounded retries, `KEEPTTL`) |
+  | `pg`                                         | cross-server (one upsert, keeps `expires_at`) | cross-server (`DELETE … RETURNING`)   | cross-server (compare-and-set, bounded retries)                |
+  | `memory` / `memoryExtended` / `lru` / `mock` | in-process, synchronous                       | in-process, synchronous               | serialized per key, in-process only                            |
+  | `file`                                       | serialized per key, in-process only           | serialized per key, in-process only   | not supported (throws)                                         |
 
   `update()` callbacks on Redis and Postgres may run more than once under contention, so keep them side-effect free. To coordinate more than one server, use `redis` or `pg`; `memory` is per-process.
+
 - **Tag index primitives** on the driver contract: `tagAdd`, `tagMembers`, `tagRemove`. Redis uses a native SET inside the prefix (a legacy JSON index is upgraded on first touch), Postgres a one-statement JSON-array merge on the index row, and the in-memory drivers a separate store that eviction and expiry never touch. `file` and `null` keep the serialized fallback. `invalidate()` deletes exactly the members it read, writes prune up to 20 dead members, `remove()`/`pull()` detach the key, and tagged `increment`/`pull` use the atomic ops.
 - **`PgCacheDriver.prune(limit = 1000)`** deletes expired rows in batches and returns the count. `set()` also runs it in the background on about 1 in 200 writes, so unique-key workloads no longer grow the table forever.
 - **`lock()` successor-safe release** (see Fixed). There is no renewal, so the TTL must exceed the worst-case duration of the locked work.
@@ -230,7 +254,7 @@ changelogs.
 - Removed the raw `console.log(value)` dump of the full cached payload when `structuredClone` fails in `parseCachedData` — cached values (potentially PII/tokens) no longer leak to stdout; the structured error log with the value's type is kept.
 - **Credential leak via error logging (Medium):** `logError()` and the Redis driver's `connect()` failure path printed the raw `Error` object straight to stdout (`console.log`) or to `log.fatal`, which could include the connection URL — and password — that some Redis/Node client errors echo back in `error.message`/`cause` on connection failure. Both call sites now go through a new `safeErrorInfo()` helper that logs only a redacted `{ message, code }` shape (never the raw error object), with any `scheme://user:pass@` credentials in the message masked to `scheme://[REDACTED]@`. The bare `console.log(error)`/`console.log("Err", error)` calls are gone entirely.
 - **Redis `removeNamespace` blocking `KEYS` scan (Medium):** replaced the blocking `KEYS` command with a non-blocking `SCAN` cursor loop (`client.scanIterator`), so clearing a namespace on a large keyspace no longer stalls the single-threaded Redis event loop for every other tenant/consumer. The existing glob-escaping fix (above) is unchanged.
-- **File driver `removeNamespace` dotted-key gap (Medium):** dotted keys (`ns.a`) are stored as *sibling* directories under the cache root (see the path-traversal fix above), so removing namespace `ns` — which only ever deleted a directory literally named `ns` — silently left every `ns.*` key on disk. `removeNamespace` now lists the cache root's immediate children, decodes each back to its logical key, and removes every directory whose logical key equals the namespace or starts with `<namespace>.`, matching the boundary semantics the `pg` driver already used for the same contract. Honors `globalPrefix` (previously ignored, so a global flush could wipe the whole cache root instead of scoping to the tenant) and preserves the existing path-containment guard.
+- **File driver `removeNamespace` dotted-key gap (Medium):** dotted keys (`ns.a`) are stored as _sibling_ directories under the cache root (see the path-traversal fix above), so removing namespace `ns` — which only ever deleted a directory literally named `ns` — silently left every `ns.*` key on disk. `removeNamespace` now lists the cache root's immediate children, decodes each back to its logical key, and removes every directory whose logical key equals the namespace or starts with `<namespace>.`, matching the boundary semantics the `pg` driver already used for the same contract. Honors `globalPrefix` (previously ignored, so a global flush could wipe the whole cache root instead of scoping to the tenant) and preserves the existing path-containment guard.
 
 ### Dependencies
 

package/README.md

@@ -33,11 +33,7 @@ Or
 First step, we need to define the cache configurations, in your configuration directory create a file to define the cache configurations.
 
 ```ts
-import {
-  cache,
-  type CacheConfigurations,
-  MemoryCacheDriver,
-} from "@mongez/warlock.cache";
+import { cache, type CacheConfigurations, MemoryCacheDriver } from "@mongez/warlock.cache";
 
 const configurations: CacheConfigurations = {
   drivers: {
@@ -102,11 +98,11 @@ await cache.set("report", report, "7d");
 
 // 3. Rich options object
 await cache.set("user:1", user, {
-  ttl: "1h",                     // or number of seconds — mutually exclusive with expiresAt
-  expiresAt: new Date("..."),    // absolute deadline (Date or epoch ms)
-  tags: ["users", "active"],     // inline tags
-  onConflict: "create",          // "create" | "update" | "upsert" (default)
-  driver: "redis",               // route this single call to a non-default driver
+  ttl: "1h", // or number of seconds — mutually exclusive with expiresAt
+  expiresAt: new Date("..."), // absolute deadline (Date or epoch ms)
+  tags: ["users", "active"], // inline tags
+  onConflict: "create", // "create" | "update" | "upsert" (default)
+  driver: "redis", // route this single call to a non-default driver
 });
 ```
 
@@ -117,8 +113,8 @@ cache.setCacheConfigurations({
   default: "redis",
   drivers: { redis: RedisCacheDriver, memory: MemoryCacheDriver },
   options: {
-    redis: { url: "...", ttl: "7d" },     // string OK
-    memory: { ttl: 3600 },                 // number OK
+    redis: { url: "...", ttl: "7d" }, // string OK
+    memory: { ttl: 3600 }, // number OK
   },
 });
 ```
@@ -142,7 +138,7 @@ Redis users who know the shorthand: `"create"` maps to `NX`, `"update"` maps to
 ```ts
 // Read → transform → write under a per-key in-process lock.
 await cache.update<User>("user:1", (current) => {
-  if (!current) return null;                     // returning null removes the entry
+  if (!current) return null; // returning null removes the entry
   return { ...current, lastSeen: Date.now() };
 });
 
@@ -166,7 +162,7 @@ const head = await recent.shift();
 const firstTen = await recent.slice(0, 10);
 const count = await recent.length();
 
-await recent.trim(0, 99);   // keep only indices 0–99
+await recent.trim(0, 99); // keep only indices 0–99
 await recent.clear();
 ```
 
@@ -231,11 +227,7 @@ It could be useful when working with multi tenant applications, we can use the t
 Every driver's options have by default `globalPrefix` async function, this function is called each time an operation is performed, and it returns a string, this string is used as a prefix for the key, let's add it to our memory driver.
 
 ```ts
-import {
-  cache,
-  type CacheConfigurations,
-  MemoryCacheDriver,
-} from "@mongez/warlock.cache";
+import { cache, type CacheConfigurations, MemoryCacheDriver } from "@mongez/warlock.cache";
 
 const configurations: CacheConfigurations = {
   drivers: {
@@ -416,10 +408,9 @@ async function main() {
 }
 ```
 
-
 ### LRU Cache Driver
 
-[LRU Cache](https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)) is a cache driver that caches the data in the memory with LRU algorithm.
+[LRU Cache](<https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)>) is a cache driver that caches the data in the memory with LRU algorithm.
 
 So how this works? The LRU cache driver will store the data in the memory, and when the memory is full, it will remove the least recently used item.