redis-graph-cache 1.0.0

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

@@ -0,0 +1,148 @@
+/**
+ * Atomic Lua scripts for race-free Redis operations.
+ *
+ * Each script is registered on the ioredis client via `defineCommand` and
+ * exposed as a typed method (see redis-connection-manager.ts).
+ *
+ * Why Lua: Redis executes a Lua script as a single atomic unit, so we get
+ * compare-and-set, conditional writes, and array mutations without
+ * client-side races, WATCH/MULTI overhead, or extra round-trips.
+ */
+/**
+ * Compare-and-set. Writes `newValue` only if the current value at `key`
+ * exactly equals `expectedValue`. Empty-string `expectedValue` means
+ * "expect key to not exist".
+ *
+ * KEYS[1] = entity key
+ * ARGV[1] = expected current value (or "" to expect absence)
+ * ARGV[2] = new value
+ * ARGV[3] = ttl seconds (0 or negative = no expiry)
+ *
+ * Returns: 1 on success, 0 on conflict.
+ */
+export declare const CAS_SET_SCRIPT = "\nlocal current = redis.call('GET', KEYS[1])\nlocal expected = ARGV[1]\nif expected == \"\" then\n  if current then return 0 end\nelse\n  if current ~= expected then return 0 end\nend\nlocal ttl = tonumber(ARGV[3])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], ARGV[2], 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], ARGV[2])\nend\nreturn 1\n";
+/**
+ * Set the value only if the key already exists. Used for "update only if
+ * cached" semantics so we don't accidentally warm the cache for unread data.
+ *
+ * KEYS[1] = entity key
+ * ARGV[1] = new value
+ * ARGV[2] = ttl seconds (0 or negative = no expiry)
+ *
+ * Returns: 1 on success, 0 if key did not exist.
+ */
+export declare const SET_IF_EXISTS_SCRIPT = "\nif redis.call('EXISTS', KEYS[1]) == 0 then return 0 end\nlocal ttl = tonumber(ARGV[2])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], ARGV[1], 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], ARGV[1])\nend\nreturn 1\n";
+/**
+ * Atomically add an id to a JSON-array list value. Idempotent: if the id is
+ * already present, no write happens and 0 is returned. The list value is
+ * stored as a JSON array string (e.g. "[1,2,3]"). When the key is missing,
+ * a new single-element array is created.
+ *
+ * Note: cjson.encode of an empty Lua table yields "{}" rather than "[]".
+ * We never encode an empty list here because we always insert exactly one
+ * element, so this is safe.
+ *
+ * KEYS[1] = list key
+ * ARGV[1] = id (always passed as string; numeric ids are stringified by the
+ *           caller and re-parsed when read)
+ * ARGV[2] = ttl seconds (0 or negative = no expiry)
+ * ARGV[3] = "1" if id should be coerced back to number when stored, else "0"
+ *
+ * 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";
+/**
+ * Atomically remove an id from a JSON-array list value. If the resulting
+ * list is empty, writes the literal "[]" (avoiding cjson's {} ambiguity).
+ *
+ * KEYS[1] = list key
+ * ARGV[1] = id (always passed as string)
+ *
+ * Returns: 1 if removed, 0 if list missing or id not found.
+ */
+export declare const LIST_REMOVE_SCRIPT = "\nlocal current = redis.call('GET', KEYS[1])\nif not current then return 0 end\nlocal ids = cjson.decode(current)\nif type(ids) ~= 'table' then return 0 end\nlocal needle = ARGV[1]\nlocal found = false\nlocal out = {}\nfor i = 1, #ids do\n  if tostring(ids[i]) == needle and not found then\n    found = true\n  else\n    table.insert(out, ids[i])\n  end\nend\nif not found then return 0 end\nlocal encoded\nif #out == 0 then\n  encoded = '[]'\nelse\n  encoded = cjson.encode(out)\nend\nlocal ttl = redis.call('TTL', KEYS[1])\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";
+/**
+ * Atomic ZADD into a sorted set, with optional max-size trim and optional
+ * 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.
+ *
+ * KEYS[1] = ZSET list key
+ * KEYS[2] = membership back-index key (ignored when ARGV[5] = "0")
+ * ARGV[1] = numeric score (passed as string; Redis parses)
+ * ARGV[2] = member id (always passed as string)
+ * ARGV[3] = ttl seconds (0 = no expiry refresh)
+ * 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";
+/**
+ * Atomic ZREM with optional back-index cleanup. Returns 1 if removed, 0
+ * if the member was not in the set.
+ *
+ * KEYS[1] = ZSET list key
+ * KEYS[2] = membership back-index key (ignored when ARGV[2] = "0")
+ * ARGV[1] = member id
+ * ARGV[2] = "1" to maintain back-index, "0" otherwise
+ *
+ * Note: we don't SREM the list key from the back-index here because we
+ * only know that *this* id was removed; other ids in the same list may
+ * still reference it. The back-index entry is per-id, and the SADD/SREM
+ * pairing is balanced across `addIndexedListItem` and the cascade path.
+ */
+export declare const ZLIST_REMOVE_SCRIPT = "\nlocal removed = redis.call('ZREM', KEYS[1], ARGV[1])\nif removed > 0 and ARGV[2] == \"1\" then\n  -- Membership entries are id-scoped: if THIS id has no other tracked\n  -- lists pointing at it (i.e. we're the last reference), the back-index\n  -- still keeps the listKey -> see comment above. We intentionally leave\n  -- the back-index alone here; cascade invalidation cleans it up.\nend\nreturn removed\n";
+/**
+ * Cascade-invalidate: read every list key from the back-index for an
+ * entity, ZREM the entity from each, then delete the entity key itself
+ * and the back-index. All atomic in one round-trip.
+ *
+ * KEYS[1] = membership back-index key (e.g. __rse_membership:post:42)
+ * KEYS[2] = entity key (e.g. post:42)
+ * ARGV[1] = member id (string form, used for ZREM)
+ *
+ * Returns: number of lists the entity was removed from.
+ *
+ * Robustness: if any list key has already been deleted (TTL expired,
+ * manually removed, etc.) ZREM is a no-op for that key, which is the
+ * desired behaviour.
+ */
+export declare const CASCADE_INVALIDATE_SCRIPT = "\nlocal lists = redis.call('SMEMBERS', KEYS[1])\nlocal removed = 0\nfor i = 1, #lists do\n  local r = redis.call('ZREM', lists[i], ARGV[1])\n  if r > 0 then removed = removed + 1 end\nend\nredis.call('DEL', KEYS[1])\nredis.call('DEL', KEYS[2])\nreturn removed\n";
+/**
+ * Names used when registering scripts with ioredis.defineCommand.
+ * These become methods on the redis client instance with the same name.
+ */
+export declare const SCRIPT_DEFINITIONS: readonly [{
+    readonly name: "rseCasSet";
+    readonly script: "\nlocal current = redis.call('GET', KEYS[1])\nlocal expected = ARGV[1]\nif expected == \"\" then\n  if current then return 0 end\nelse\n  if current ~= expected then return 0 end\nend\nlocal ttl = tonumber(ARGV[3])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], ARGV[2], 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], ARGV[2])\nend\nreturn 1\n";
+    readonly numberOfKeys: 1;
+}, {
+    readonly name: "rseSetIfExists";
+    readonly script: "\nif redis.call('EXISTS', KEYS[1]) == 0 then return 0 end\nlocal ttl = tonumber(ARGV[2])\nif ttl and ttl > 0 then\n  redis.call('SET', KEYS[1], ARGV[1], 'EX', ttl)\nelse\n  redis.call('SET', KEYS[1], ARGV[1])\nend\nreturn 1\n";
+    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 numberOfKeys: 1;
+}, {
+    readonly name: "rseListRemove";
+    readonly script: "\nlocal current = redis.call('GET', KEYS[1])\nif not current then return 0 end\nlocal ids = cjson.decode(current)\nif type(ids) ~= 'table' then return 0 end\nlocal needle = ARGV[1]\nlocal found = false\nlocal out = {}\nfor i = 1, #ids do\n  if tostring(ids[i]) == needle and not found then\n    found = true\n  else\n    table.insert(out, ids[i])\n  end\nend\nif not found then return 0 end\nlocal encoded\nif #out == 0 then\n  encoded = '[]'\nelse\n  encoded = cjson.encode(out)\nend\nlocal ttl = redis.call('TTL', KEYS[1])\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 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 numberOfKeys: 2;
+}, {
+    readonly name: "rseZListRemove";
+    readonly script: "\nlocal removed = redis.call('ZREM', KEYS[1], ARGV[1])\nif removed > 0 and ARGV[2] == \"1\" then\n  -- Membership entries are id-scoped: if THIS id has no other tracked\n  -- lists pointing at it (i.e. we're the last reference), the back-index\n  -- still keeps the listKey -> see comment above. We intentionally leave\n  -- the back-index alone here; cascade invalidation cleans it up.\nend\nreturn removed\n";
+    readonly numberOfKeys: 2;
+}, {
+    readonly name: "rseCascadeInvalidate";
+    readonly script: "\nlocal lists = redis.call('SMEMBERS', KEYS[1])\nlocal removed = 0\nfor i = 1, #lists do\n  local r = redis.call('ZREM', lists[i], ARGV[1])\n  if r > 0 then removed = removed + 1 end\nend\nredis.call('DEL', KEYS[1])\nredis.call('DEL', KEYS[2])\nreturn removed\n";
+    readonly numberOfKeys: 2;
+}];
+export type ScriptName = (typeof SCRIPT_DEFINITIONS)[number]['name'];

package/dist/core/lua-scripts.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Atomic Lua scripts for race-free Redis operations.
+ *
+ * Each script is registered on the ioredis client via `defineCommand` and
+ * exposed as a typed method (see redis-connection-manager.ts).
+ *
+ * Why Lua: Redis executes a Lua script as a single atomic unit, so we get
+ * compare-and-set, conditional writes, and array mutations without
+ * client-side races, WATCH/MULTI overhead, or extra round-trips.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPT_DEFINITIONS = exports.CASCADE_INVALIDATE_SCRIPT = exports.ZLIST_REMOVE_SCRIPT = exports.ZLIST_ADD_SCRIPT = exports.LIST_REMOVE_SCRIPT = exports.LIST_ADD_SCRIPT = exports.SET_IF_EXISTS_SCRIPT = exports.CAS_SET_SCRIPT = void 0;
+/**
+ * Compare-and-set. Writes `newValue` only if the current value at `key`
+ * exactly equals `expectedValue`. Empty-string `expectedValue` means
+ * "expect key to not exist".
+ *
+ * KEYS[1] = entity key
+ * ARGV[1] = expected current value (or "" to expect absence)
+ * ARGV[2] = new value
+ * ARGV[3] = ttl seconds (0 or negative = no expiry)
+ *
+ * Returns: 1 on success, 0 on conflict.
+ */
+exports.CAS_SET_SCRIPT = `
+local current = redis.call('GET', KEYS[1])
+local expected = ARGV[1]
+if expected == "" then
+  if current then return 0 end
+else
+  if current ~= expected then return 0 end
+end
+local ttl = tonumber(ARGV[3])
+if ttl and ttl > 0 then
+  redis.call('SET', KEYS[1], ARGV[2], 'EX', ttl)
+else
+  redis.call('SET', KEYS[1], ARGV[2])
+end
+return 1
+`;
+/**
+ * Set the value only if the key already exists. Used for "update only if
+ * cached" semantics so we don't accidentally warm the cache for unread data.
+ *
+ * KEYS[1] = entity key
+ * ARGV[1] = new value
+ * ARGV[2] = ttl seconds (0 or negative = no expiry)
+ *
+ * Returns: 1 on success, 0 if key did not exist.
+ */
+exports.SET_IF_EXISTS_SCRIPT = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return 0 end
+local ttl = tonumber(ARGV[2])
+if ttl and ttl > 0 then
+  redis.call('SET', KEYS[1], ARGV[1], 'EX', ttl)
+else
+  redis.call('SET', KEYS[1], ARGV[1])
+end
+return 1
+`;
+/**
+ * Atomically add an id to a JSON-array list value. Idempotent: if the id is
+ * already present, no write happens and 0 is returned. The list value is
+ * stored as a JSON array string (e.g. "[1,2,3]"). When the key is missing,
+ * a new single-element array is created.
+ *
+ * Note: cjson.encode of an empty Lua table yields "{}" rather than "[]".
+ * We never encode an empty list here because we always insert exactly one
+ * element, so this is safe.
+ *
+ * KEYS[1] = list key
+ * ARGV[1] = id (always passed as string; numeric ids are stringified by the
+ *           caller and re-parsed when read)
+ * ARGV[2] = ttl seconds (0 or negative = no expiry)
+ * ARGV[3] = "1" if id should be coerced back to number when stored, else "0"
+ *
+ * Returns: 1 if added, 0 if already present.
+ */
+exports.LIST_ADD_SCRIPT = `
+local current = redis.call('GET', KEYS[1])
+local ids
+if current then
+  ids = cjson.decode(current)
+  if type(ids) ~= 'table' then ids = {} end
+else
+  ids = {}
+end
+local needle = ARGV[1]
+for i = 1, #ids do
+  if tostring(ids[i]) == needle then return 0 end
+end
+local toInsert
+if ARGV[3] == "1" then
+  toInsert = tonumber(needle)
+  if toInsert == nil then toInsert = needle end
+else
+  toInsert = needle
+end
+table.insert(ids, toInsert)
+local encoded = cjson.encode(ids)
+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)
+end
+return 1
+`;
+/**
+ * Atomically remove an id from a JSON-array list value. If the resulting
+ * list is empty, writes the literal "[]" (avoiding cjson's {} ambiguity).
+ *
+ * KEYS[1] = list key
+ * ARGV[1] = id (always passed as string)
+ *
+ * Returns: 1 if removed, 0 if list missing or id not found.
+ */
+exports.LIST_REMOVE_SCRIPT = `
+local current = redis.call('GET', KEYS[1])
+if not current then return 0 end
+local ids = cjson.decode(current)
+if type(ids) ~= 'table' then return 0 end
+local needle = ARGV[1]
+local found = false
+local out = {}
+for i = 1, #ids do
+  if tostring(ids[i]) == needle and not found then
+    found = true
+  else
+    table.insert(out, ids[i])
+  end
+end
+if not found then return 0 end
+local encoded
+if #out == 0 then
+  encoded = '[]'
+else
+  encoded = cjson.encode(out)
+end
+local ttl = redis.call('TTL', KEYS[1])
+if ttl and ttl > 0 then
+  redis.call('SET', KEYS[1], encoded, 'EX', ttl)
+else
+  redis.call('SET', KEYS[1], encoded)
+end
+return 1
+`;
+/**
+ * Atomic ZADD into a sorted set, with optional max-size trim and optional
+ * 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.
+ *
+ * KEYS[1] = ZSET list key
+ * KEYS[2] = membership back-index key (ignored when ARGV[5] = "0")
+ * ARGV[1] = numeric score (passed as string; Redis parses)
+ * ARGV[2] = member id (always passed as string)
+ * ARGV[3] = ttl seconds (0 = no expiry refresh)
+ * ARGV[4] = max size (0 = no trim)
+ * ARGV[5] = "1" to maintain back-index, "0" otherwise
+ */
+exports.ZLIST_ADD_SCRIPT = `
+local added = redis.call('ZADD', KEYS[1], ARGV[1], ARGV[2])
+if ARGV[5] == "1" then
+  redis.call('SADD', KEYS[2], KEYS[1])
+end
+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)
+  end
+end
+local ttl = tonumber(ARGV[3])
+if ttl and ttl > 0 then
+  redis.call('EXPIRE', KEYS[1], ttl)
+  if ARGV[5] == "1" then
+    -- Back-index TTL is set to a generous multiple of the list TTL so the
+    -- index outlives any one list TTL refresh. Without this it could
+    -- expire while the list still references it, leaving cascade
+    -- invalidation unable to find tracked lists. 4x is empirically safe.
+    redis.call('EXPIRE', KEYS[2], ttl * 4)
+  end
+end
+return added
+`;
+/**
+ * Atomic ZREM with optional back-index cleanup. Returns 1 if removed, 0
+ * if the member was not in the set.
+ *
+ * KEYS[1] = ZSET list key
+ * KEYS[2] = membership back-index key (ignored when ARGV[2] = "0")
+ * ARGV[1] = member id
+ * ARGV[2] = "1" to maintain back-index, "0" otherwise
+ *
+ * Note: we don't SREM the list key from the back-index here because we
+ * only know that *this* id was removed; other ids in the same list may
+ * still reference it. The back-index entry is per-id, and the SADD/SREM
+ * pairing is balanced across `addIndexedListItem` and the cascade path.
+ */
+exports.ZLIST_REMOVE_SCRIPT = `
+local removed = redis.call('ZREM', KEYS[1], ARGV[1])
+if removed > 0 and ARGV[2] == "1" then
+  -- Membership entries are id-scoped: if THIS id has no other tracked
+  -- lists pointing at it (i.e. we're the last reference), the back-index
+  -- still keeps the listKey -> see comment above. We intentionally leave
+  -- the back-index alone here; cascade invalidation cleans it up.
+end
+return removed
+`;
+/**
+ * Cascade-invalidate: read every list key from the back-index for an
+ * entity, ZREM the entity from each, then delete the entity key itself
+ * and the back-index. All atomic in one round-trip.
+ *
+ * KEYS[1] = membership back-index key (e.g. __rse_membership:post:42)
+ * KEYS[2] = entity key (e.g. post:42)
+ * ARGV[1] = member id (string form, used for ZREM)
+ *
+ * Returns: number of lists the entity was removed from.
+ *
+ * Robustness: if any list key has already been deleted (TTL expired,
+ * manually removed, etc.) ZREM is a no-op for that key, which is the
+ * desired behaviour.
+ */
+exports.CASCADE_INVALIDATE_SCRIPT = `
+local lists = redis.call('SMEMBERS', KEYS[1])
+local removed = 0
+for i = 1, #lists do
+  local r = redis.call('ZREM', lists[i], ARGV[1])
+  if r > 0 then removed = removed + 1 end
+end
+redis.call('DEL', KEYS[1])
+redis.call('DEL', KEYS[2])
+return removed
+`;
+/**
+ * Names used when registering scripts with ioredis.defineCommand.
+ * These become methods on the redis client instance with the same name.
+ */
+exports.SCRIPT_DEFINITIONS = [
+    { name: 'rseCasSet', script: exports.CAS_SET_SCRIPT, numberOfKeys: 1 },
+    { name: 'rseSetIfExists', script: exports.SET_IF_EXISTS_SCRIPT, numberOfKeys: 1 },
+    { name: 'rseListAdd', script: exports.LIST_ADD_SCRIPT, numberOfKeys: 1 },
+    { name: 'rseListRemove', script: exports.LIST_REMOVE_SCRIPT, numberOfKeys: 1 },
+    { name: 'rseZListAdd', script: exports.ZLIST_ADD_SCRIPT, numberOfKeys: 2 },
+    { name: 'rseZListRemove', script: exports.ZLIST_REMOVE_SCRIPT, numberOfKeys: 2 },
+    {
+        name: 'rseCascadeInvalidate',
+        script: exports.CASCADE_INVALIDATE_SCRIPT,
+        numberOfKeys: 2,
+    },
+];

package/dist/core/normalization-engine.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Normalization Engine - Converts nested objects into normalized Redis storage
+ */
+import { SchemaManager } from './schema-manager';
+import { RedisConnectionManager } from './redis-connection-manager';
+import { CompressionCodec } from './compression';
+import { Serializer } from './serializer';
+import { NormalizedEntity, WriteResult } from '../types';
+export interface NormalizationResult {
+    normalizedEntities: Map<string, NormalizedEntity>;
+    primaryEntityKey: string;
+    operationId: string;
+}
+export declare class NormalizationEngine {
+    private schemaManager;
+    private connectionManager;
+    private codec;
+    private serializer;
+    constructor(schemaManager: SchemaManager, connectionManager: RedisConnectionManager, codec?: CompressionCodec, serializer?: Serializer);
+    /**
+     * Normalize a complex nested entity into separate Redis keys
+     */
+    normalizeEntity(entityType: string, data: any, operationId?: string): Promise<NormalizationResult>;
+    /**
+     * Write normalized entities to Redis using a per-key compare-and-set so
+     * concurrent writers cannot clobber each other's partial updates. The
+     * caller-supplied entity-type lookup determines TTL per key.
+     *
+     * Flow per key:
+     *   1. GET current value
+     *   2. Merge in Node (preserves "missing fields keep existing" semantics)
+     *   3. CAS write via Lua. If another writer raced us, retry up to
+     *      `maxCasAttempts` times with the freshly read value.
+     *
+     * All keys are processed in parallel (Promise.all) and ioredis pipelines
+     * them automatically across the same connection, so latency stays close
+     * to the original implementation while gaining atomicity.
+     */
+    writeNormalizedEntities(normalizationResult: NormalizationResult, resolveTTL?: (key: string) => number): Promise<WriteResult>;
+    /**
+     * Per-key compare-and-set merge with bounded retry. Each retry re-reads
+     * the current value so the merge is always against the freshest view.
+     * Surfaces a RedisConnectionError if the contention budget is exhausted,
+     * which is the right behaviour: callers should retry at the request level
+     * rather than spin forever inside a single write.
+     */
+    private atomicMergeWrite;
+    /**
+     * Recursively normalize entity and its relationships
+     */
+    private normalizeRecursive;
+    /**
+     * Process a relationship and normalize related entities
+     */
+    private processRelationship;
+    /**
+     * Smart merge strategy based on field types
+     */
+    private smartMerge;
+    /**
+     * Check if value is primitive (string, number, boolean, null, undefined)
+     */
+    private isPrimitiveValue;
+    /**
+     * Check if value is a plain object
+     */
+    private isObject;
+    /**
+     * Deep merge two objects
+     */
+    private deepMergeObjects;
+    /**
+     * Generate unique operation ID
+     */
+    private generateOperationId;
+}