@warlock.js/cache 5.30.0 → 5.31.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ 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 (FW-04).
+- 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
 
@@ -87,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
@@ -130,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.
@@ -242,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.
 

package/cjs/index.cjs

@@ -666,8 +666,8 @@ var TaggedScopedCache = class {
 	* Atomic counter increment on the scoped key. Tags aren't applied to
 	* subsequent increments — they're attached at first-write time.
 	*/
-	increment(key, value) {
-		return this.scope.increment(key, value);
+	increment(key, value, options) {
+		return this.scope.increment(key, value, options);
 	}
 	/**
 	* Atomic counter decrement on the scoped key. See {@link increment}.
@@ -860,8 +860,8 @@ var ScopedCache = class ScopedCache {
 	* Atomic counter increment on the scoped key. TTL is preserved by the
 	* underlying driver — scope ttl is only applied on first write via `set`.
 	*/
-	increment(key, value) {
-		return this.source.increment(this.scopedKey(key), value);
+	increment(key, value, options) {
+		return this.source.increment(this.scopedKey(key), value, { ttl: options?.ttl ?? this.defaults.ttl });
 	}
 	/**
 	* Atomic counter decrement on the scoped key. See {@link increment} for
@@ -1321,9 +1321,9 @@ var CacheManager = class {
 	/**
 	* {@inheritdoc}
 	*/
-	async increment(key, value) {
+	async increment(key, value, options) {
 		this.ensureDriverInitialized();
-		return this.currentDriver.increment(key, value);
+		return this.currentDriver.increment(key, value, options);
 	}
 	/**
 	* {@inheritdoc}
@@ -1902,8 +1902,8 @@ var TaggedCache = class TaggedCache {
 	/**
 	* {@inheritdoc}
 	*/
-	async increment(key, value = 1) {
-		const newValue = await this.driver.increment(key, value);
+	async increment(key, value = 1, options) {
+		const newValue = await this.driver.increment(key, value, options);
 		await this.storeTaggedKey(key);
 		return newValue;
 	}
@@ -2319,7 +2319,8 @@ var BaseCacheDriver = class {
 	* The remaining TTL is rounded down, so repeated increments can never push
 	* a window's deadline later.
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
+		const ttl = options.ttl === void 0 ? this.ttl : parseTtl(options.ttl);
 		const parsedKey = this.parseKey(key);
 		return this.runSerialized(parsedKey, async () => {
 			const entry = await this.getEntry(key);
@@ -2330,8 +2331,8 @@ var BaseCacheDriver = class {
 			const base = current === null || current === void 0 ? 0 : current;
 			if (typeof base !== "number") throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 			const newValue = base + value;
-			if (!live) await this.set(key, newValue);
-			else if (expiresAt == null || expiresAt === Infinity) await this.set(key, newValue, { ttl: Infinity });
+			if (!live) await this.set(key, newValue, { ttl });
+			else if (expiresAt == null || expiresAt === Infinity) await this.set(key, newValue, { ttl: options.ttl === void 0 ? Infinity : ttl });
 			else await this.set(key, newValue, { ttl: Math.max(1, Math.floor((expiresAt - now) / 1e3)) });
 			return newValue;
 		});
@@ -3132,7 +3133,8 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 	* concurrent increments in this process never lose an update. An existing
 	* node keeps its expiry; a missing key starts from 0 with the default TTL.
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
+		const ttl = options.ttl === void 0 ? this.ttl : parseTtl(options.ttl);
 		const parsedKey = this.parseKey(key);
 		const node = this.liveNode(parsedKey);
 		const current = node ? node.value : 0;
@@ -3140,9 +3142,10 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		const newValue = current + value;
 		if (node) {
 			node.value = newValue;
+			if (options.ttl !== void 0 && !Number.isFinite(node.expiresAt) && Number.isFinite(ttl) && ttl > 0) node.expiresAt = Date.now() + ttl * 1e3;
 			this.moveHead(node);
 		} else {
-			const newNode = new CacheNode(parsedKey, newValue, this.ttl);
+			const newNode = new CacheNode(parsedKey, newValue, ttl);
 			this.cache.set(parsedKey, newNode);
 			this.addNode(newNode);
 			if (this.cache.size > this.capacity) this.removeTail();
@@ -3150,7 +3153,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		await this.emit("set", {
 			key: parsedKey,
 			value: newValue,
-			ttl: this.ttl
+			ttl
 		});
 		return newValue;
 	}
@@ -3503,7 +3506,8 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 	* concurrent increments in this process never lose an update. An existing
 	* entry keeps its expiry; a missing key starts from 0 with the default TTL.
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
+		const ttl = options.ttl === void 0 ? this.ttl : parseTtl(options.ttl);
 		const parsedKey = this.parseKey(key);
 		const entry = this.readLive(parsedKey);
 		const current = entry ? entry.data : 0;
@@ -3511,9 +3515,14 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 		const newValue = current + value;
 		if (entry) {
 			entry.data = newValue;
+			if (options.ttl !== void 0 && !Number.isFinite(entry.expiresAt) && Number.isFinite(ttl) && ttl > 0) {
+				entry.ttl = ttl;
+				entry.expiresAt = Date.now() + ttl * 1e3;
+				this.expiry.set(parsedKey, entry.expiresAt);
+			}
 			this.touch(parsedKey, entry);
 		} else {
-			const data = this.prepareDataForStorage(newValue, this.ttl);
+			const data = this.prepareDataForStorage(newValue, ttl);
 			this.entries.set(parsedKey, data);
 			if (data.expiresAt !== void 0 && Number.isFinite(data.expiresAt)) this.expiry.set(parsedKey, data.expiresAt);
 			this.enforceMaxSize(parsedKey);
@@ -3521,7 +3530,7 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 		await this.emit("set", {
 			key: parsedKey,
 			value: newValue,
-			ttl: entry?.ttl ?? this.ttl
+			ttl: entry?.ttl ?? ttl
 		});
 		return newValue;
 	}
@@ -3873,19 +3882,25 @@ var MockCacheDriver = class extends BaseCacheDriver {
 	* Synchronous read-add-write (atomic within the process). Keeps an existing
 	* entry's expiry; a missing key starts from 0 with the default TTL.
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
+		const ttl = options.ttl === void 0 ? this.ttl : parseTtl(options.ttl);
 		const parsedKey = this.parseKey(key);
 		this.recordCall("increment", parsedKey, [value]);
 		const entry = this.liveEntry(parsedKey);
 		const current = entry ? entry.data : 0;
 		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 		const newValue = current + value;
-		if (entry) entry.data = newValue;
-		else this.storage.set(parsedKey, this.prepareDataForStorage(newValue, this.ttl));
+		if (entry) {
+			entry.data = newValue;
+			if (options.ttl !== void 0 && !Number.isFinite(entry.expiresAt) && Number.isFinite(ttl) && ttl > 0) {
+				entry.ttl = ttl;
+				entry.expiresAt = Date.now() + ttl * 1e3;
+			}
+		} else this.storage.set(parsedKey, this.prepareDataForStorage(newValue, ttl));
 		await this.emit("set", {
 			key: parsedKey,
 			value: newValue,
-			ttl: this.ttl
+			ttl
 		});
 		return newValue;
 	}
@@ -4562,7 +4577,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 	* keeps its `expires_at`; a missing or expired row restarts from `value`
 	* with the driver default TTL. A non-numeric live value is rejected.
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
 		const parsedKey = this.parseKey(key);
 		const t = this.table;
 		const expired = `${t}.expires_at IS NOT NULL AND ${t}.expires_at <= now()`;
@@ -4571,13 +4586,16 @@ var PgCacheDriver = class extends BaseCacheDriver {
        ON CONFLICT (key) DO UPDATE
          SET value = CASE WHEN ${expired} THEN EXCLUDED.value
                           ELSE to_jsonb((${t}.value #>> '{}')::numeric + $2::numeric) END,
-             expires_at = CASE WHEN ${expired} THEN EXCLUDED.expires_at ELSE ${t}.expires_at END,
+             expires_at = CASE WHEN ${expired} THEN EXCLUDED.expires_at
+                               WHEN $4::boolean AND ${t}.expires_at IS NULL THEN EXCLUDED.expires_at
+                               ELSE ${t}.expires_at END,
              stale_at = CASE WHEN ${expired} THEN NULL ELSE ${t}.stale_at END
          WHERE (${expired}) OR jsonb_typeof(${t}.value) = 'number'
        RETURNING value`, [
 			parsedKey,
 			value,
-			this.ttlToSeconds(this.ttl)
+			this.ttlToSeconds(options.ttl === void 0 ? this.ttl : parseTtl(options.ttl)),
+			options.ttl !== void 0
 		]);
 		if (rows.length === 0) throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 		const newValue = Number(this.decodeJson(rows[0].value));
@@ -4845,7 +4863,7 @@ const REDIS_GET_DEL_SCRIPT = `local v = redis.call('GET', KEYS[1])
 if v then redis.call('DEL', KEYS[1]) end
 return v`;
 /**
-* Increment that gives a counter without an expiry the driver's default TTL,
+* Increment that gives a counter without an expiry its per-call or default TTL,
 * in one round trip.
 *
 * KEYS[1]=key; ARGV[1]=amount; ARGV[2]=ttl seconds ('0' = none).
@@ -5289,10 +5307,11 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 	* Atomic increment using Redis native INCRBY command
 	* {@inheritdoc}
 	*/
-	async increment(key, value = 1) {
+	async increment(key, value = 1, options = {}) {
 		const parsedKey = this.parseKey(key);
 		this.log("caching", parsedKey);
-		const defaultTtl = Number.isFinite(this.ttl) && this.ttl > 0 ? Math.ceil(this.ttl) : 0;
+		const ttl = options.ttl === void 0 ? this.ttl : parseTtl(options.ttl);
+		const defaultTtl = Number.isFinite(ttl) && ttl > 0 ? Math.ceil(ttl) : 0;
 		const result = defaultTtl > 0 ? Number(await this.client?.eval(REDIS_INCREMENT_SCRIPT, {
 			keys: [parsedKey],
 			arguments: [String(value), String(defaultTtl)]