LibSharedVariables-1.0

LibSharedVariables-1.0 is a lightweight storage helper for World of Warcraft addons. It provides a merged db proxy view over per-character and account-wide saved variables, with optional defaults for each scope and automatic table creation.

Features

• Merged read view across character DB, account DB, and optional defaults.
• Automatic creation of global saved variable tables (<name>PCDB and <name>DB).
• Smart write routing based on existing key ownership/default scope.
• Reusable handles by addon name (calling Load again refreshes references/defaults).
• Simple helper methods (Get, Set) and pairs() support on merged db.

Quick Start

local LSV = LibStub("LibSharedVariables-1.0")
if not LSV then return end

local defaults = {
    profileVersion = 1,
    minimap = true,
}

local defaultsPC = {
    firstRun = true,
}

local function handleOnLoad(db, handle)
    if db.firstRun then
        print("Welcome on this character")
        db.firstRun = false
    end

    handle.accountDB.lastLoadedAt = date("%Y-%m-%d %H:%M:%S")
end

local handle = LSV:Load("MyAddon", defaults, defaultsPC, handleOnLoad)

Read and Write Behavior

Read lookup order for db[key] is:

1. Character DB (<name>PCDB)
2. Account DB (<name>DB)
3. Character defaults (defaultsPC)
4. Account defaults (defaults)

Write behavior for db[key] = value:

• If key already exists in character DB, write to character DB.
• Else if key exists in defaultsPC, write to character DB.
• Else if key exists in defaults, write to account DB.
• Else write to character DB.

This allows account-style defaults and character-style defaults to naturally map to the expected persistence scope.

OnLoad Callback

LSV:Load("MyAddon", defaults, defaultsPC, function(db, handle)
    if db.firstRun then
        print("Welcome on this character")
        db.firstRun = false
    end

    -- handle.accountDB and handle.charDB are direct table references
end)

Iteration

You can iterate merged keys using pairs(db). Duplicate keys are returned once, respecting read precedence.

for key, value in pairs(db) do
    print(key, value)
end

API

• lib:Load(name, defaults?, defaultsPC?, onLoad?) -> handle
• handle.db[key] (merged reads/writes via metatable)
• handle:Get(key, default?) -> value
• handle:Set(key, value) -> value

handle fields:

• handle.name
• handle.accountDB
• handle.charDB
• handle.defaults
• handle.defaultsPC
• handle.db

Notes

• name must be a non-empty string.
• onLoad, when provided, must be a function.
• Calling Load again with the same name reuses the existing handle and refreshes DB table references/defaults.
• Ensure your addon TOC declares matching saved variable names for persistence.

License

• GPL-3.0 - see LICENSE.