redis-graph-cache 1.0.1 → 1.0.3

package/dist/core/hydration-engine.js

@@ -51,8 +51,18 @@ class HydrationEngine {
         }
         // Create separate context for each entity to prevent cross-contamination
         const results = await Promise.all(ids.map((id) => this.hydrateEntity(entityType, id, options)));
-        // Filter out null results (deleted entities)
-        return results.filter((result) => result !== null);
+        // Filter out null results (deleted entities). A non-zero gap between
+        // requested ids and returned results usually means entity keys have
+        // expired while the list ZSET is still alive (TTL coherence skew).
+        const hydrated = results.filter((result) => result !== null);
+        const missing = results.length - hydrated.length;
+        if (missing > 0) {
+            console.warn(`[RedisGraphCache] hydrateEntities: ${missing} of ${results.length} ` +
+                `'${entityType}' entity keys were missing in Redis. ` +
+                `This usually means entity TTL <= list TTL — set entity TTL to at least ` +
+                `2\u00d7 the list TTL to prevent silent result truncation.`);
+        }
+        return hydrated;
     }
     /**
      * Create hydration context with limits and tracking
@@ -162,7 +172,22 @@ class HydrationEngine {
             if (context.excludeRelations?.includes(relationName)) {
                 continue;
             }
-            const promise = this.hydrateRelation(relationName, relationDef, normalizedEntity, hydratedEntity, context);
+            // Fork the visited-set per relation branch, synchronously, before any
+            // async work starts. `visitedEntities` tracks the *current path* for
+            // cycle detection (add on enter, delete on exit in `hydrateRecursive`).
+            // Sibling relations are hydrated concurrently (Promise.all below), so if
+            // they shared one Set, one branch's transient in-progress entries would
+            // leak into a sibling's view — making a shared entity referenced by both
+            // a parent and its child collection (a diamond, not a cycle) resolve to a
+            // `$ref` stub instead of the full object. A per-branch clone captures
+            // only the ancestor path, so real cycles down a branch are still caught
+            // while concurrent siblings stay isolated. This mirrors the per-item
+            // clone `batchHydrateEntities` already performs for `many` relations.
+            const branchContext = {
+                ...context,
+                visitedEntities: new Set(context.visitedEntities),
+            };
+            const promise = this.hydrateRelation(relationName, relationDef, normalizedEntity, hydratedEntity, branchContext);
             relationPromises.push(promise);
         }
         // Execute all relationship hydrations in parallel
@@ -174,7 +199,9 @@ class HydrationEngine {
     async hydrateRelation(relationName, relationDef, normalizedEntity, hydratedEntity, context) {
         const relationIdField = (0, types_1.generateRelationIdField)(relationName, relationDef.kind);
         const relationIds = normalizedEntity[relationIdField];
-        if (!relationIds) {
+        // Explicit missing/cleared check (not falsy): a stored reference id of
+        // 0 is a legitimate key and must hydrate, not resolve to null.
+        if (relationIds === null || relationIds === undefined) {
             // No relation data, set appropriate default
             hydratedEntity[relationName] = relationDef.kind === 'one' ? null : [];
             return;
@@ -226,8 +253,17 @@ class HydrationEngine {
             return this.hydrateRecursive(entityType, id, entityContext);
         });
         const results = await Promise.all(hydrationPromises);
-        // Filter out null results (deleted entities)
-        return results.filter((result) => result !== null);
+        // Filter out null results (deleted entities). Log when the gap is
+        // non-zero so TTL coherence skew is visible in application logs.
+        const hydrated = results.filter((result) => result !== null);
+        const missing = results.length - hydrated.length;
+        if (missing > 0) {
+            console.warn(`[RedisGraphCache] batchHydrateEntities: ${missing} of ${results.length} ` +
+                `'${entityType}' entity keys were missing in Redis. ` +
+                `This usually means entity TTL <= list TTL — set entity TTL to at least ` +
+                `2\u00d7 the list TTL to prevent silent result truncation.`);
+        }
+        return hydrated;
     }
     /**
      * Get a single entity from Redis. Hits/misses are tracked by the

package/dist/core/lua-scripts.d.ts

@@ -50,7 +50,7 @@ export declare const SET_IF_EXISTS_SCRIPT = "\nif redis.call('EXISTS', KEYS[1])
  *
  * Returns: 1 if added, 0 if already present.
  */
-export declare const LIST_ADD_SCRIPT = "\nlocal current = redis.call('GET', KEYS[1])\nlocal ids\nif current then\n  ids = cjson.decode(current)\n  if type(ids) ~= 'table' then ids = {} end\nelse\n  ids = {}\nend\nlocal needle = ARGV[1]\nfor i = 1, #ids do\n  if tostring(ids[i]) == needle then return 0 end\nend\nlocal toInsert\nif ARGV[3] == \"1\" then\n  toInsert = tonumber(needle)\n  if toInsert == nil then toInsert = needle end\nelse\n  toInsert = needle\nend\ntable.insert(ids, toInsert)\nlocal encoded = cjson.encode(ids)\nlocal ttl = tonumber(ARGV[2])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], encoded, 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], encoded)\nend\nreturn 1\n";
+export declare const LIST_ADD_SCRIPT = "\nlocal current = redis.call('GET', KEYS[1])\nlocal ids\nif current then\n  ids = cjson.decode(current)\n  if type(ids) ~= 'table' then ids = {} end\nelse\n  ids = {}\nend\nlocal needle = ARGV[1]\nfor i = 1, #ids do\n  if tostring(ids[i]) == needle then return 0 end\nend\nlocal toInsert\nif ARGV[3] == \"1\" then\n  toInsert = tonumber(needle)\n  if toInsert == nil then toInsert = needle end\nelse\n  toInsert = needle\nend\ntable.insert(ids, toInsert)\nlocal encoded = cjson.encode(ids)\nlocal ttl = tonumber(ARGV[2])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], encoded, 'EX', ttl)\nelse\n  -- No ttl for this write: PRESERVE the key's remaining TTL instead of\n  -- stripping it (a bare SET clears expiry). Mirrors LIST_REMOVE, which\n  -- already carries the remaining TTL across the rewrite.\n  local remaining = redis.call('TTL', KEYS[1])\n  if remaining and remaining > 0 then\n    redis.call('SET', KEYS[1], encoded, 'EX', remaining)\n  else\n    redis.call('SET', KEYS[1], encoded)\n  end\nend\nreturn 1\n";
 /**
  * Atomically remove an id from a JSON-array list value. If the resulting
  * list is empty, writes the literal "[]" (avoiding cjson's {} ambiguity).
@@ -66,11 +66,16 @@ export declare const LIST_REMOVE_SCRIPT = "\nlocal current = redis.call('GET', K
  * back-index update for cascade invalidation. Returns 1 if a new member
  * was added, 0 if the score was updated on an existing member.
  *
- * Trimming uses ZREMRANGEBYRANK to discard the lowest-scored members so
- * that exactly `maxSize` items remain. This works correctly whether the
- * list is being read newest-first (ZREVRANGE) or oldest-first (ZRANGE):
- * the lowest score is always the "oldest" by whatever score axis is in
- * use.
+ * Trimming discards the lowest-scored members so that exactly `maxSize`
+ * items remain — i.e. the retention policy is "keep the highest scores"
+ * (newest, for timestamp scores). Note for oldest-first consumers: a
+ * capped list always retains the top of the score axis regardless of
+ * read direction.
+ *
+ * The trim explicitly never evicts the member being added: with score
+ * ties Redis orders members lexicographically, so a plain
+ * ZREMRANGEBYRANK 0..N could nondeterministically remove the member
+ * that was just ZADDed (e.g. many same-second timestamps).
  *
  * KEYS[1] = ZSET list key
  * KEYS[2] = membership back-index key (ignored when ARGV[5] = "0")
@@ -80,7 +85,7 @@ export declare const LIST_REMOVE_SCRIPT = "\nlocal current = redis.call('GET', K
  * ARGV[4] = max size (0 = no trim)
  * ARGV[5] = "1" to maintain back-index, "0" otherwise
  */
-export declare const ZLIST_ADD_SCRIPT = "\nlocal added = redis.call('ZADD', KEYS[1], ARGV[1], ARGV[2])\nif ARGV[5] == \"1\" then\n  redis.call('SADD', KEYS[2], KEYS[1])\nend\nlocal maxSize = tonumber(ARGV[4])\nif maxSize and maxSize > 0 then\n  local size = redis.call('ZCARD', KEYS[1])\n  if size > maxSize then\n    redis.call('ZREMRANGEBYRANK', KEYS[1], 0, size - maxSize - 1)\n  end\nend\nlocal ttl = tonumber(ARGV[3])\nif ttl and ttl > 0 then\n  redis.call('EXPIRE', KEYS[1], ttl)\n  if ARGV[5] == \"1\" then\n    -- Back-index TTL is set to a generous multiple of the list TTL so the\n    -- index outlives any one list TTL refresh. Without this it could\n    -- expire while the list still references it, leaving cascade\n    -- invalidation unable to find tracked lists. 4x is empirically safe.\n    redis.call('EXPIRE', KEYS[2], ttl * 4)\n  end\nend\nreturn added\n";
+export declare const ZLIST_ADD_SCRIPT = "\nlocal added = redis.call('ZADD', KEYS[1], ARGV[1], ARGV[2])\nif ARGV[5] == \"1\" then\n  redis.call('SADD', KEYS[2], KEYS[1])\nend\nlocal maxSize = tonumber(ARGV[4])\nif maxSize and maxSize > 0 then\n  local size = redis.call('ZCARD', KEYS[1])\n  if size > maxSize then\n    local toRemove = size - maxSize\n    -- Fetch one extra candidate so we can skip the just-added member if\n    -- a score tie placed it among the lowest ranks.\n    local victims = redis.call('ZRANGE', KEYS[1], 0, toRemove)\n    local removed = 0\n    for i = 1, #victims do\n      if removed >= toRemove then break end\n      if victims[i] ~= ARGV[2] then\n        redis.call('ZREM', KEYS[1], victims[i])\n        removed = removed + 1\n      end\n    end\n  end\nend\nlocal ttl = tonumber(ARGV[3])\nif ttl and ttl > 0 then\n  redis.call('EXPIRE', KEYS[1], ttl)\n  if ARGV[5] == \"1\" then\n    -- Back-index TTL is set to a generous multiple of the list TTL so the\n    -- index outlives any one list TTL refresh. Without this it could\n    -- expire while the list still references it, leaving cascade\n    -- invalidation unable to find tracked lists. 4x is empirically safe.\n    redis.call('EXPIRE', KEYS[2], ttl * 4)\n  end\nend\nreturn added\n";
 /**
  * Atomic ZREM with optional back-index cleanup. Returns 1 if removed, 0
  * if the member was not in the set.
@@ -126,7 +131,7 @@ export declare const SCRIPT_DEFINITIONS: readonly [{
     readonly numberOfKeys: 1;
 }, {
     readonly name: "rseListAdd";
-    readonly script: "\nlocal current = redis.call('GET', KEYS[1])\nlocal ids\nif current then\n  ids = cjson.decode(current)\n  if type(ids) ~= 'table' then ids = {} end\nelse\n  ids = {}\nend\nlocal needle = ARGV[1]\nfor i = 1, #ids do\n  if tostring(ids[i]) == needle then return 0 end\nend\nlocal toInsert\nif ARGV[3] == \"1\" then\n  toInsert = tonumber(needle)\n  if toInsert == nil then toInsert = needle end\nelse\n  toInsert = needle\nend\ntable.insert(ids, toInsert)\nlocal encoded = cjson.encode(ids)\nlocal ttl = tonumber(ARGV[2])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], encoded, 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], encoded)\nend\nreturn 1\n";
+    readonly script: "\nlocal current = redis.call('GET', KEYS[1])\nlocal ids\nif current then\n  ids = cjson.decode(current)\n  if type(ids) ~= 'table' then ids = {} end\nelse\n  ids = {}\nend\nlocal needle = ARGV[1]\nfor i = 1, #ids do\n  if tostring(ids[i]) == needle then return 0 end\nend\nlocal toInsert\nif ARGV[3] == \"1\" then\n  toInsert = tonumber(needle)\n  if toInsert == nil then toInsert = needle end\nelse\n  toInsert = needle\nend\ntable.insert(ids, toInsert)\nlocal encoded = cjson.encode(ids)\nlocal ttl = tonumber(ARGV[2])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], encoded, 'EX', ttl)\nelse\n  -- No ttl for this write: PRESERVE the key's remaining TTL instead of\n  -- stripping it (a bare SET clears expiry). Mirrors LIST_REMOVE, which\n  -- already carries the remaining TTL across the rewrite.\n  local remaining = redis.call('TTL', KEYS[1])\n  if remaining and remaining > 0 then\n    redis.call('SET', KEYS[1], encoded, 'EX', remaining)\n  else\n    redis.call('SET', KEYS[1], encoded)\n  end\nend\nreturn 1\n";
     readonly numberOfKeys: 1;
 }, {
     readonly name: "rseListRemove";
@@ -134,7 +139,7 @@ export declare const SCRIPT_DEFINITIONS: readonly [{
     readonly numberOfKeys: 1;
 }, {
     readonly name: "rseZListAdd";
-    readonly script: "\nlocal added = redis.call('ZADD', KEYS[1], ARGV[1], ARGV[2])\nif ARGV[5] == \"1\" then\n  redis.call('SADD', KEYS[2], KEYS[1])\nend\nlocal maxSize = tonumber(ARGV[4])\nif maxSize and maxSize > 0 then\n  local size = redis.call('ZCARD', KEYS[1])\n  if size > maxSize then\n    redis.call('ZREMRANGEBYRANK', KEYS[1], 0, size - maxSize - 1)\n  end\nend\nlocal ttl = tonumber(ARGV[3])\nif ttl and ttl > 0 then\n  redis.call('EXPIRE', KEYS[1], ttl)\n  if ARGV[5] == \"1\" then\n    -- Back-index TTL is set to a generous multiple of the list TTL so the\n    -- index outlives any one list TTL refresh. Without this it could\n    -- expire while the list still references it, leaving cascade\n    -- invalidation unable to find tracked lists. 4x is empirically safe.\n    redis.call('EXPIRE', KEYS[2], ttl * 4)\n  end\nend\nreturn added\n";
+    readonly script: "\nlocal added = redis.call('ZADD', KEYS[1], ARGV[1], ARGV[2])\nif ARGV[5] == \"1\" then\n  redis.call('SADD', KEYS[2], KEYS[1])\nend\nlocal maxSize = tonumber(ARGV[4])\nif maxSize and maxSize > 0 then\n  local size = redis.call('ZCARD', KEYS[1])\n  if size > maxSize then\n    local toRemove = size - maxSize\n    -- Fetch one extra candidate so we can skip the just-added member if\n    -- a score tie placed it among the lowest ranks.\n    local victims = redis.call('ZRANGE', KEYS[1], 0, toRemove)\n    local removed = 0\n    for i = 1, #victims do\n      if removed >= toRemove then break end\n      if victims[i] ~= ARGV[2] then\n        redis.call('ZREM', KEYS[1], victims[i])\n        removed = removed + 1\n      end\n    end\n  end\nend\nlocal ttl = tonumber(ARGV[3])\nif ttl and ttl > 0 then\n  redis.call('EXPIRE', KEYS[1], ttl)\n  if ARGV[5] == \"1\" then\n    -- Back-index TTL is set to a generous multiple of the list TTL so the\n    -- index outlives any one list TTL refresh. Without this it could\n    -- expire while the list still references it, leaving cascade\n    -- invalidation unable to find tracked lists. 4x is empirically safe.\n    redis.call('EXPIRE', KEYS[2], ttl * 4)\n  end\nend\nreturn added\n";
     readonly numberOfKeys: 2;
 }, {
     readonly name: "rseZListRemove";

package/dist/core/lua-scripts.js

@@ -103,7 +103,15 @@ local ttl = tonumber(ARGV[2])
 if ttl and ttl > 0 then
   redis.call('SET', KEYS[1], encoded, 'EX', ttl)
 else
-  redis.call('SET', KEYS[1], encoded)
+  -- No ttl for this write: PRESERVE the key's remaining TTL instead of
+  -- stripping it (a bare SET clears expiry). Mirrors LIST_REMOVE, which
+  -- already carries the remaining TTL across the rewrite.
+  local remaining = redis.call('TTL', KEYS[1])
+  if remaining and remaining > 0 then
+    redis.call('SET', KEYS[1], encoded, 'EX', remaining)
+  else
+    redis.call('SET', KEYS[1], encoded)
+  end
 end
 return 1
 `;
@@ -151,11 +159,16 @@ return 1
  * back-index update for cascade invalidation. Returns 1 if a new member
  * was added, 0 if the score was updated on an existing member.
  *
- * Trimming uses ZREMRANGEBYRANK to discard the lowest-scored members so
- * that exactly `maxSize` items remain. This works correctly whether the
- * list is being read newest-first (ZREVRANGE) or oldest-first (ZRANGE):
- * the lowest score is always the "oldest" by whatever score axis is in
- * use.
+ * Trimming discards the lowest-scored members so that exactly `maxSize`
+ * items remain — i.e. the retention policy is "keep the highest scores"
+ * (newest, for timestamp scores). Note for oldest-first consumers: a
+ * capped list always retains the top of the score axis regardless of
+ * read direction.
+ *
+ * The trim explicitly never evicts the member being added: with score
+ * ties Redis orders members lexicographically, so a plain
+ * ZREMRANGEBYRANK 0..N could nondeterministically remove the member
+ * that was just ZADDed (e.g. many same-second timestamps).
  *
  * KEYS[1] = ZSET list key
  * KEYS[2] = membership back-index key (ignored when ARGV[5] = "0")
@@ -174,7 +187,18 @@ local maxSize = tonumber(ARGV[4])
 if maxSize and maxSize > 0 then
   local size = redis.call('ZCARD', KEYS[1])
   if size > maxSize then
-    redis.call('ZREMRANGEBYRANK', KEYS[1], 0, size - maxSize - 1)
+    local toRemove = size - maxSize
+    -- Fetch one extra candidate so we can skip the just-added member if
+    -- a score tie placed it among the lowest ranks.
+    local victims = redis.call('ZRANGE', KEYS[1], 0, toRemove)
+    local removed = 0
+    for i = 1, #victims do
+      if removed >= toRemove then break end
+      if victims[i] ~= ARGV[2] then
+        redis.call('ZREM', KEYS[1], victims[i])
+        removed = removed + 1
+      end
+    end
   end
 end
 local ttl = tonumber(ARGV[3])

package/dist/core/normalization-engine.js

@@ -125,7 +125,9 @@ class NormalizationEngine {
         }
         const schema = this.schemaManager.getEntitySchema(entityType);
         const entityId = data[schema.id];
-        if (!entityId) {
+        // Explicit check (not falsy): numeric id 0 is a legitimate primary key
+        // and must not be rejected as "missing".
+        if (entityId === undefined || entityId === null || entityId === '') {
             throw new types_1.InvalidOperationError('normalize', `Missing required ID field '${schema.id}' in entity '${entityType}'`, { entityType, data });
         }
         const entityKey = this.schemaManager.generateEntityKey(entityType, entityId);
@@ -174,9 +176,20 @@ class NormalizationEngine {
         const relationIdField = (0, types_1.generateRelationIdField)(relationName, relationDef.kind);
         if (relationDef.kind === 'one') {
             // One-to-one relationship
-            if (relationData && typeof relationData === 'object') {
+            if (relationData === null) {
+                // Explicit null CLEARS the reference — same contract as regular
+                // fields ("explicit null is a real overwrite"). Without this, a
+                // caller switching a relation off (e.g. comment.ownerPage → null)
+                // leaves the old __rse_<name>Id in place forever via smart-merge,
+                // and reads keep hydrating the stale related entity.
+                parentEntity[relationIdField] = null;
+                const metadata = parentEntity[types_1.METADATA_FIELD];
+                metadata.relationshipIds[relationName] = null;
+            }
+            else if (relationData && typeof relationData === 'object') {
                 const relatedId = relationData[relatedSchema.id];
-                if (relatedId) {
+                // Explicit check: id 0 is a valid key and must not be skipped.
+                if (relatedId !== undefined && relatedId !== null && relatedId !== '') {
                     parentEntity[relationIdField] = relatedId;
                     // Store relationship ID in metadata
                     const metadata = parentEntity[types_1.METADATA_FIELD];
@@ -185,28 +198,41 @@ class NormalizationEngine {
                     await this.normalizeRecursive(relationDef.type, relationData, result, operationId, visited);
                 }
             }
+            // undefined / field omitted: preserved by smart-merge (unchanged).
         }
         else if (relationDef.kind === 'many') {
             // One-to-many relationship
-            if (Array.isArray(relationData)) {
+            if (relationData === null) {
+                // Explicit null clears the whole collection (stored as [] so
+                // hydration keeps returning an array).
+                parentEntity[relationIdField] = [];
+                const metadata = parentEntity[types_1.METADATA_FIELD];
+                metadata.relationshipIds[relationName] = [];
+            }
+            else if (Array.isArray(relationData)) {
                 const relatedIds = [];
                 for (const relatedItem of relationData) {
                     if (relatedItem && typeof relatedItem === 'object') {
                         const relatedId = relatedItem[relatedSchema.id];
-                        if (relatedId) {
+                        // Explicit check: id 0 is a valid key and must not be skipped.
+                        if (relatedId !== undefined &&
+                            relatedId !== null &&
+                            relatedId !== '') {
                             relatedIds.push(relatedId);
                             // Recursively normalize related entity
                             await this.normalizeRecursive(relationDef.type, relatedItem, result, operationId, visited);
                         }
                     }
                 }
-                if (relatedIds.length > 0) {
-                    parentEntity[relationIdField] = relatedIds;
-                    // Store relationship IDs in metadata
-                    const metadata = parentEntity[types_1.METADATA_FIELD];
-                    metadata.relationshipIds[relationName] = relatedIds;
-                }
+                // Arrays have documented replace-entirely semantics, so an empty
+                // array must clear the collection too — the old `length > 0`
+                // guard made `[]` silently preserve stale members.
+                parentEntity[relationIdField] = relatedIds;
+                // Store relationship IDs in metadata
+                const metadata = parentEntity[types_1.METADATA_FIELD];
+                metadata.relationshipIds[relationName] = relatedIds;
             }
+            // undefined / field omitted: preserved by smart-merge (unchanged).
         }
     }
     /**

package/dist/core/redis-connection-manager.d.ts

@@ -199,9 +199,12 @@ export declare class RedisConnectionManager {
      * owns and never blocks the Redis server on large keyspaces.
      *
      * Implementation notes:
-     *   - `SCAN` with `{ match: '*' }` works correctly because ioredis
-     *     automatically prepends `keyPrefix` to the `MATCH` pattern on
-     *     the wire, so Redis only returns keys under our namespace.
+     *   - The `MATCH` pattern must include the prefix explicitly: ioredis
+     *     only prefixes recognized KEY arguments, and SCAN's MATCH is a
+     *     pattern, not a key — it goes to the wire verbatim. (An earlier
+     *     version assumed auto-prefixing and scanned the ENTIRE keyspace
+     *     with `match: '*'`; the startsWith filter below kept that safe
+     *     but O(total DB size) on shared Redis instances.)
      *   - Redis returns the fully-prefixed keys. We strip the prefix
      *     before calling `UNLINK`, because ioredis re-applies the prefix
      *     on outbound commands — passing the raw prefixed keys would

package/dist/core/redis-connection-manager.js

@@ -140,13 +140,19 @@ class RedisConnectionManager {
                 this.connectedFlags[idx] = true;
                 this.healthMetrics.recordConnection();
             });
+            // The circuit breaker is deliberately NOT wired to socket events:
+            // it is driven exclusively by real operation outcomes in
+            // `executeOperation`. Wiring it here had two failure modes — a
+            // flapping socket's background 'error' events (fired every ~2s by
+            // the ioredis retryStrategy) tripped the breaker for the whole pool
+            // with zero user traffic, and each such event refreshed
+            // `lastFailureTime`, starving `shouldAttemptReset` so the breaker
+            // could never reach HALF_OPEN on its own.
             client.on('ready', () => {
                 this.connectedFlags[idx] = true;
-                this.circuitBreaker.onSuccess();
             });
             client.on('error', (error) => {
                 this.healthMetrics.recordError();
-                this.circuitBreaker.onFailure();
                 console.error(`[RedisSchemaEngine] Redis client #${idx} error:`, error.message);
             });
             client.on('close', () => {
@@ -165,7 +171,14 @@ class RedisConnectionManager {
     async connect() {
         try {
             await Promise.all(this.clients.map(async (client, idx) => {
-                await client.connect();
+                // ioredis rejects connect() unless the client is in 'wait'
+                // (lazyConnect) or 'end' state. Clients auto-connect at
+                // construction, so calling connect() on an already-connecting/
+                // connected client used to throw every time — making this
+                // method unusable. Skip clients that are already on their way.
+                if (client.status === 'wait' || client.status === 'end') {
+                    await client.connect();
+                }
                 this.connectedFlags[idx] = true;
             }));
         }
@@ -456,9 +469,12 @@ class RedisConnectionManager {
      * owns and never blocks the Redis server on large keyspaces.
      *
      * Implementation notes:
-     *   - `SCAN` with `{ match: '*' }` works correctly because ioredis
-     *     automatically prepends `keyPrefix` to the `MATCH` pattern on
-     *     the wire, so Redis only returns keys under our namespace.
+     *   - The `MATCH` pattern must include the prefix explicitly: ioredis
+     *     only prefixes recognized KEY arguments, and SCAN's MATCH is a
+     *     pattern, not a key — it goes to the wire verbatim. (An earlier
+     *     version assumed auto-prefixing and scanned the ENTIRE keyspace
+     *     with `match: '*'`; the startsWith filter below kept that safe
+     *     but O(total DB size) on shared Redis instances.)
      *   - Redis returns the fully-prefixed keys. We strip the prefix
      *     before calling `UNLINK`, because ioredis re-applies the prefix
      *     on outbound commands — passing the raw prefixed keys would
@@ -485,7 +501,7 @@ class RedisConnectionManager {
             // SCAN in batches of 500. Larger counts reduce round-trips but
             // increase per-call work on the Redis side; 500 is a safe middle
             // ground that performs well on keyspaces well past the 100k mark.
-            const stream = client.scanStream({ match: '*', count: 500 });
+            const stream = client.scanStream({ match: `${prefix}*`, count: 500 });
             await new Promise((resolve, reject) => {
                 stream.on('data', (keys) => {
                     if (!keys || keys.length === 0)
@@ -572,9 +588,24 @@ class RedisConnectionManager {
                 if (this.connectedFlags[idx]) {
                     await client.quit();
                 }
+                else {
+                    // A client that is mid-reconnect (flag false) still owns
+                    // active retry timers and a socket; skipping it left those
+                    // alive and kept the Node event loop from exiting after
+                    // disconnect(). Force-close it.
+                    client.disconnect();
+                }
             }
             catch (error) {
                 console.error(`[RedisSchemaEngine] Disconnect error on client #${idx}:`, error);
+                // quit() can fail on a broken connection; force-close so no
+                // retry timers survive.
+                try {
+                    client.disconnect();
+                }
+                catch {
+                    // already closed
+                }
             }
             finally {
                 this.connectedFlags[idx] = false;
@@ -671,9 +702,29 @@ class RetryManager {
             'ETIMEDOUT',
             'ENOTFOUND',
             'ECONNREFUSED',
+            'EPIPE',
             'Connection is closed',
+            'Command timed out',
         ];
-        return retryableMessages.some((msg) => error.message.includes(msg) || error.name.includes(msg));
+        // Operations reach this classifier already wrapped (executeOperation
+        // rethrows a RedisConnectionError whose message never contains the
+        // network error code — the raw ioredis error lives only in `.cause`).
+        // Matching only the top error's message/name made every real network
+        // failure look non-retryable, silently disabling retries entirely.
+        // Walk the cause chain and match message, name, and code per level.
+        let current = error;
+        let depth = 0;
+        while (current && depth < 5) {
+            const message = String(current.message ?? '');
+            const name = String(current.name ?? '');
+            const code = String(current.code ?? '');
+            if (retryableMessages.some((msg) => message.includes(msg) || name.includes(msg) || code === msg)) {
+                return true;
+            }
+            current = current.cause ?? current.originalError;
+            depth++;
+        }
+        return false;
     }
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/core/schema-manager.js

@@ -85,6 +85,12 @@ class SchemaManager {
                 warnings: validationResult.warnings,
             });
         }
+        // Emit warnings even when the schema is valid. These are non-fatal
+        // design issues (e.g. TTL coherence skew) that will not prevent the
+        // cache from running but can cause subtle bugs in production.
+        for (const warning of validationResult.warnings) {
+            console.warn(`[RedisGraphCache] Schema warning: ${warning}`);
+        }
     }
     /**
      * Get entity schema by name
@@ -191,6 +197,23 @@ class SchemaManager {
         if (circularDeps.length > 0) {
             warnings.push(`Circular dependencies detected: ${circularDeps.join(', ')}`);
         }
+        // TTL coherence check: warn when an indexedList TTL >= its entity TTL.
+        // addIndexedListItem refreshes the ZSET TTL on every insert but does NOT
+        // refresh existing member entity TTLs. If both TTLs are equal, late
+        // inserts push the ZSET expiry forward while older entity keys expire at
+        // the original deadline — reads silently return fewer items than exist.
+        // Entity TTL should be at least 2× the list TTL to prevent this.
+        for (const [listName, listSchema] of this.indexedListSchemas) {
+            const entityTtl = this.resolveEntityTTL(listSchema.entityType);
+            const listTtl = listSchema.ttl ?? this.defaultTTL;
+            // ttl=0 means "no expiry" — no skew risk.
+            if (listTtl > 0 && entityTtl > 0 && entityTtl <= listTtl) {
+                warnings.push(`TTL coherence: indexed list '${listName}' has ttl=${listTtl}s but ` +
+                    `its entity type '${listSchema.entityType}' has ttl=${entityTtl}s. ` +
+                    `Entity TTL must be greater than list TTL (recommend >= 2×) to prevent ` +
+                    `silent result truncation when the list ZSET outlives its member entity keys.`);
+            }
+        }
         return {
             isValid: errors.length === 0,
             errors,

package/dist/core/serializer.js

@@ -117,41 +117,54 @@ function tagReviver(_key, value) {
         !(TAG in value)) {
         return value;
     }
-    switch (value[TAG]) {
-        case 'Date':
-            // `null` in `v` means we serialized an Invalid Date; reconstruct
-            // it so identity round-trips even for that weird case.
-            return value.v === null ? new Date(NaN) : new Date(value.v);
-        case 'BigInt':
-            return BigInt(value.v);
-        case 'Map':
-            return new Map(value.v);
-        case 'Set':
-            return new Set(value.v);
-        case 'RegExp':
-            return new RegExp(value.src, value.flags);
-        case 'Buffer':
-            // Guarded for non-Node environments. If Buffer is unavailable
-            // we return the raw envelope so the consumer at least sees the
-            // base64 payload rather than getting `undefined`.
-            if (typeof Buffer !== 'undefined') {
-                return Buffer.from(value.v, 'base64');
-            }
-            return value;
-        case 'Number':
-            if (value.v === 'NaN')
-                return NaN;
-            if (value.v === 'Infinity')
-                return Infinity;
-            if (value.v === '-Infinity')
-                return -Infinity;
-            return Number(value.v);
-        default:
-            // Unknown tag — return the envelope as-is. This is forward
-            // compatible: a future engine version may add new tags and
-            // older readers will simply pass them through instead of
-            // crashing.
-            return value;
+    // The tag guard above only proves the object LOOKS like an engine
+    // envelope. User data stored inside an `object`-typed field can contain
+    // a lookalike (e.g. `{ __rse_t: 'BigInt', v: 'abc' }`) — schema
+    // validation rejects `__rse_`-prefixed FIELD NAMES, but not nested
+    // object contents. A malformed lookalike must never throw out of the
+    // reviver: that would abort JSON.parse and make the whole entity
+    // permanently unreadable. On any revival failure, return the raw
+    // envelope so the caller at least sees the stored data.
+    try {
+        switch (value[TAG]) {
+            case 'Date':
+                // `null` in `v` means we serialized an Invalid Date; reconstruct
+                // it so identity round-trips even for that weird case.
+                return value.v === null ? new Date(NaN) : new Date(value.v);
+            case 'BigInt':
+                return BigInt(value.v);
+            case 'Map':
+                return new Map(value.v);
+            case 'Set':
+                return new Set(value.v);
+            case 'RegExp':
+                return new RegExp(value.src, value.flags);
+            case 'Buffer':
+                // Guarded for non-Node environments. If Buffer is unavailable
+                // we return the raw envelope so the consumer at least sees the
+                // base64 payload rather than getting `undefined`.
+                if (typeof Buffer !== 'undefined') {
+                    return Buffer.from(value.v, 'base64');
+                }
+                return value;
+            case 'Number':
+                if (value.v === 'NaN')
+                    return NaN;
+                if (value.v === 'Infinity')
+                    return Infinity;
+                if (value.v === '-Infinity')
+                    return -Infinity;
+                return Number(value.v);
+            default:
+                // Unknown tag — return the envelope as-is. This is forward
+                // compatible: a future engine version may add new tags and
+                // older readers will simply pass them through instead of
+                // crashing.
+                return value;
+        }
+    }
+    catch {
+        return value;
     }
 }
 /**

package/dist/redis-graph-cache.js

@@ -90,8 +90,17 @@ class RedisGraphCache {
         // that value wins for that key regardless of cascade rules. Every
         // other key still goes through `base`, so embedded children keep
         // their schema TTL unless `cascadeTTL` lifts them.
-        if (overrideKey === undefined || overrideTtl === undefined)
+        //
+        // NaN / negative overrides are ignored per the documented contract
+        // ("falls back to schema TTL") — previously a NaN ttl leaked through
+        // here and the write landed with NO expiry, silently overriding the
+        // schema TTL.
+        if (overrideKey === undefined ||
+            overrideTtl === undefined ||
+            !Number.isFinite(overrideTtl) ||
+            overrideTtl < 0) {
             return base;
+        }
         return (key) => (key === overrideKey ? overrideTtl : base(key));
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redis-graph-cache",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A TypeScript-first Redis data layer with schema-driven normalization, relationship management, and graph-based hydration for high-performance Node.js applications.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",