NampowerDB — New Shared Library (nampowerDB.lua)

A reusable library for crash-persistent storage via nampower's file API. Any addon can use it by calling NampowerDB_Register() at load time.

Single-file mode

The default mode. The entire SavedVariable is written to one file and read back on login.

NampowerDB_Register("MySavedVariable", "myfilename.lua", {
  periodic = true,    -- write on a timer (default: true)
  interval = 30,      -- seconds between writes (default: 30, minimum: 10)
  events   = {        -- also write when these events fire (optional)
    "AUCTION_HOUSE_CLOSED",
  },
})

Multi-file mode

Writes one file per top-level key of the SavedVariable. This is the right choice when multiple WoW accounts may be running simultaneously and sharing the same nampower file directory, since each session only writes to its own file and reads all others without conflict.

NampowerDB_Register("MySavedVariable", "myfilename_%s.lua", {
  periodic = true,
  interval = 30,
  multi_file = {
    legacy_filename = "myfilename.lua",  -- optional: old single file to read during migration
    write_key_fn = function()
      return UnitName("player")          -- key this session owns and writes
    end,
    read_keys_fn = function(globalData)  -- all keys whose files should be loaded on startup
      local keys = {}
      for k, _ in pairs(globalData) do
        if k ~= "last_saved" then
          table.insert(keys, k)
        end
      end
      return keys
    end,
  },
})

The filename argument is a string.format pattern; %s is replaced by the key. Each session writes only its own key's subtable. On login, all known per-key files are loaded and merged using a _ts timestamp stored inside each key's data, so the newest data for each key always wins regardless of which session wrote it last.

legacy_filename, if provided, is executed first on every startup. NampowerDB_Load compares its last_saved against the in-memory SavedVariable and takes whichever is newer. This preserves any crash-recovery data that was written by old single-file code before migrating to multi-file mode. Per-key files then merge on top, and their _ts timestamps are always newer, so they win for their own keys.

Behaviour

• PLAYER_LOGOUT is always added to the event list regardless of options.
• An event-triggered write resets the periodic timer to avoid a double-write shortly after.
• On login in single-file mode, last_saved timestamps are compared between the file and the in-memory SavedVariable. The newer one wins. If the SavedVariable has no last_saved (i.e. it predates this system), the file wins.
• On login in multi-file mode, each key is compared independently using _ts. A key present in a file but absent from the global is always accepted. Failures loading secondary (non-own-key) files are non-fatal and produce a chat warning rather than an error.
• If a primary file exists but fails to load or parse, an error is raised loudly. The file must be removed manually to fall back to SavedVariables. There is no silent fallback.
• If nampower is absent or older than v3.2.0, NampowerDB_Register() is a no-op and SavedVariables behaviour is unchanged.
• collectgarbage() is called immediately after each write to prevent serialization garbage from accumulating between write cycles.

Serializer

Supports strings, numbers, booleans, nil, and arbitrarily nested tables. Functions, userdata, and threads cannot be serialized and will raise an error. Output is valid Lua, loaded via ExecuteCustomLuaFile.