// MULTI/EXEC transaction: debit balance + append ledger entry
const pipeline = redis.multi()
pipeline.decrby('account:42:balance', 50)     // Command 1: debit $50
pipeline.rpush('account:42:ledger', JSON.stringify({
  type: 'debit', amount: 50, ts: Date.now()
}))                                             // Command 2: ledger entry
const results = await pipeline.exec()
// results: [[null, 950], [null, 1]]
// [error, value] pairs — null error = success

// ❌ Broken pattern: assuming EXEC failure means nothing applied
const results = await redis.multi()
  .decrby('account:42:balance', 50)
  .rpush('account:42:ledger', JSON.stringify({ type: 'debit', amount: 50 }))
  .exec()

// results might be: [[null, 950], [WRONGTYPEError, null]]
// The debit applied (950) even though the ledger write failed
// Checking only the outer exec() result misses the per-command errors

// ✅ Correct: check each result pair individually
if (results === null) {
  // EXEC returned null — WATCH detected a conflict (see §2)
  throw new Error('Transaction aborted due to concurrent modification')
}
for (const [err, value] of results) {
  if (err) {
    // A command failed — handle compensation logic
    throw new Error(`Transaction partially applied: ${err.message}`)
  }
}

# Syntax error — detected at queue time, EXEC aborts
redis-cli MULTI
redis-cli SET foo bar baz extra-arg-causes-syntax-error
# → ERR wrong number of arguments
redis-cli EXEC
# → EXECABORT Transaction discarded because of previous errors.
# No commands ran — safe.

# Runtime error — detected during execution, no rollback
redis-cli MULTI
redis-cli INCR mystring        # mystring holds "hello" — WRONGTYPE at runtime
redis-cli SET mykey myvalue    # This runs even though INCR failed
redis-cli EXEC
# → 1) ERR value is not an integer or out of range  ← INCR failed
# → 2) OK                                           ← SET succeeded
# SET ran. The dataset was mutated. No rollback.

// ✅ Optimistic locking: WATCH → MULTI → EXEC with retry
async function transferFunds(fromKey: string, toKey: string, amount: number): Promise<void> {
  const MAX_RETRIES = 5

  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    // Watch both keys — any external modification aborts the transaction
    await redis.watch(fromKey, toKey)

    const balance = parseInt(await redis.get(fromKey) ?? '0', 10)
    if (balance < amount) {
      await redis.unwatch()
      throw new Error('Insufficient funds')
    }

    const result = await redis
      .multi()
      .decrby(fromKey, amount)
      .incrby(toKey, amount)
      .exec()

    if (result !== null) {
      return // Transaction succeeded
    }
    // result === null: a concurrent client modified fromKey or toKey
    // Retry — re-read the current balance and attempt again
    await new Promise((r) => setTimeout(r, Math.random() * 50))
  }

  throw new Error('Transaction failed after maximum retries — high contention detected')
}

Timeline:
  Client A: WATCH account:42:balance   → current value: 1000
  Client B: SET account:42:balance 500
  Client B: SET account:42:balance 1000  (restored to original)
  Client A: MULTI / EXEC
  → Result: null (aborted) — WATCH detected B's modifications even though the final value is unchanged

-- EVAL script numkeys [key [key ...]] [arg [arg ...]]
-- KEYS[1..numkeys]: key names (used for cluster slot routing validation)
-- ARGV[1..N]: arbitrary arguments

-- Example: atomic check-and-set (CAS) — set only if current value matches expected
local current = redis.call('GET', KEYS[1])
if current == ARGV[1] then
  redis.call('SET', KEYS[1], ARGV[2])
  return 1  -- Success
else
  return 0  -- No-op: value changed
end

// Execute from TypeScript (ioredis)
const script = `
  local current = redis.call('GET', KEYS[1])
  if current == ARGV[1] then
    redis.call('SET', KEYS[1], ARGV[2])
    return 1
  else
    return 0
  end
`
const result = await redis.eval(
  script,
  1,                   // numkeys
  'account:42:status', // KEYS[1]
  'pending',           // ARGV[1] — expected current value
  'confirmed'          // ARGV[2] — new value to set
)
// result: 1 (applied) or 0 (value did not match expected — no-op)

-- ❌ Using pcall where call should be used — swallows unexpected errors silently
local ok = redis.pcall('INCR', KEYS[1])
-- If INCR fails with WRONGTYPE, ok = {err = "WRONGTYPE..."} and script continues
-- The caller receives the script's return value, not the error — may be misinterpreted

-- ✅ Correct: use call() for commands that must succeed; pcall() for optional side-effects
redis.call('DECRBY', KEYS[1], ARGV[1])        -- Must succeed — fail loudly if not
local logged = redis.pcall('RPUSH', KEYS[2], ARGV[2])  -- Logging is best-effort
if logged['err'] then
  -- Log the error but don't abort the critical path
end

Client A: EVAL complex_script 1 mykey → starts executing (30ms Lua computation)
Client B: GET other:key               → queued — blocked for 30ms
Client C: PING                        → queued — blocked for 30ms
Client D: SET session:99 "active"     → queued — blocked for 30ms
...30ms later...
All queued clients receive their responses simultaneously

# redis.conf
lua-time-limit 5000   # Milliseconds before server starts accepting SCRIPT KILL
# After lua-time-limit, clients receive: BUSY Redis is busy running a script
# The script continues running until: it finishes, SCRIPT KILL is issued, or server shuts down

# Kill a runaway script (only works if the script hasn't written yet — scripts with writes cannot be killed)
redis-cli SCRIPT KILL
# → OK (script killed) or ERR NOTBUSY (no script running)

# Note: if the script has performed at least one write, SCRIPT KILL returns:
# ERR UNKILLABLE Sorry the script already executed write commands
# against the dataset. You can either wait the script terminates
# or kill the server in a savage way (SHUTDOWN NOSAVE).

# Step 1: Load the script and receive its SHA1 hash
redis-cli SCRIPT LOAD "return redis.call('GET', KEYS[1])"
# → "e0e1f9fabfa9d353a0970a28c4ff7bcf81d6c9f1"

# Step 2: Execute by SHA1 — no script body transmitted
redis-cli EVALSHA e0e1f9fabfa9d353a0970a28c4ff7bcf81d6c9f1 1 mykey
# → "myvalue"

# Check if a script is loaded
redis-cli SCRIPT EXISTS e0e1f9fabfa9d353a0970a28c4ff7bcf81d6c9f1
# → 1 (loaded) or 0 (not loaded)

# Scripts are cleared by:
redis-cli SCRIPT FLUSH          # Explicitly (all scripts)
redis-cli DEBUG RELOAD          # Server config reload
# Note: RESTART also clears scripts — they are NOT persistent

// ✅ Production pattern: load once at startup, execute by SHA1 thereafter
class RedisScriptRunner {
  private sha: string | null = null
  private readonly script: string

  constructor(script: string) {
    this.script = script
  }

  async load(redis: Redis): Promise<void> {
    this.sha = await redis.script('LOAD', this.script) as string
  }

  async run(redis: Redis, numkeys: number, ...args: (string | number)[]): Promise<unknown> {
    if (!this.sha) throw new Error('Script not loaded — call load() first')
    try {
      return await redis.evalsha(this.sha, numkeys, ...args)
    } catch (err: any) {
      if (err.message.includes('NOSCRIPT')) {
        // Script was flushed (SCRIPT FLUSH or server restart) — reload and retry
        await this.load(redis)
        return await redis.evalsha(this.sha!, numkeys, ...args)
      }
      throw err
    }
  }
}

-- mylib.lua — define a named library with one function
#!lua name=mylib

local function atomic_transfer(keys, args)
  local from    = keys[1]
  local to      = keys[2]
  local amount  = tonumber(args[1])

  local balance = tonumber(redis.call('GET', from) or '0')
  if balance < amount then
    return redis.error_reply('ERR Insufficient funds')
  end

  redis.call('DECRBY', from, amount)
  redis.call('INCRBY', to,   amount)
  return redis.status_reply('OK')
end

redis.register_function('atomic_transfer', atomic_transfer)

# Load the library (survives SCRIPT FLUSH and DEBUG RELOAD)
redis-cli FUNCTION LOAD "#!lua name=mylib\n$(cat mylib.lua)"

# Execute a registered function
redis-cli FCALL atomic_transfer 2 account:42:balance account:99:balance 100

# List all loaded libraries
redis-cli FUNCTION LIST

# Dump libraries for backup/restore
redis-cli FUNCTION DUMP

-- ❌ Broken: keys in different hash slots in a Cluster
local a = redis.call('GET', 'user:42:profile')  -- slot 4041
local b = redis.call('GET', 'user:42:orders')   -- slot 5128 (different slot!)
-- CROSSSLOT error: Keys in request don't hash to the same slot

-- ✅ Correct: hash tags force all keys to the same slot
local a = redis.call('GET', '{user:42}:profile')  -- CRC16("user:42") = slot X
local b = redis.call('GET', '{user:42}:orders')   -- CRC16("user:42") = slot X (same)
-- Both keys co-located — script executes on one node