State Stores¶

store({...}) creates an explicit shared runtime-state owner. Tua derives the state shape from the initial table, so reads, replacements, updates, subscriptions, and keyed watchers receive completion and type checking without a generic annotation or package install.

local game = store({
  score = 0,
  paused = false,
  playerName = "Ada",
})

game:update(function(state)
  state.score += 10
end)

local state = game:get()
print(state.score)

local __tua_store = require("tuastore")
local game = __tua_store({
  score = 0,
  paused = false,
  playerName = "Ada",
})

game:update(function(state)
  state.score = state.score + 10
end)

local state = game:get()
print(state.score)

Store API¶

The initial table supplies the state type:

local game = store({ score = 0, paused = false })

game:set({ score = 20, paused = true }) -- accepted
game:set({ score = "high", paused = true }) -- TL1003

game:watch("score", function(value: number, previous: number)
  print(previous, value)
end)

Completion after game:get(). offers score and paused. Signature help for watch derives one overload per field, so the key and callback value type stay connected. Hovering "score" shows its state-field type, and definition on the key returns to score in the initial table. The returned unsubscribe function is idempotent. The inferred state contract is preserved when the Store is returned directly or nested in a required module table, so update(function(state) does not need a repeated annotation at the use site.

Subscriptions may be added or removed from inside a listener. The active notification keeps its original listener list, and the change takes effect on the next notification. The runtime implements this with copy-on-write listener collections, so ordinary notification does not copy every callback list.

The same applies to a mutator: update decides which values to snapshot before the mutator runs, so a subscription added from inside a mutator is first notified by the next set or update, not by the one that added it.

Share A Store Through A Module¶

Lua caches successful require results, so a normal module is enough to share one explicit store instance:

local game = store({
  score = 0,
  paused = false,
})

return game

local game = require("game_state")

local function addScore(points: number)
  local current = game:get()
  game:set({
    score = current.score + points,
    paused = current.paused,
  })
end

return { addScore = addScore }

The exported specialized store shape participates in normal module inference, so consumers retain state fields and method signatures.

Persist With LOVE¶

Runtime state and save data are separate concerns. The store does not choose a serialization format, filename, save slot, schema version, or migration policy. Use a subscription as the adapter to love.filesystem:

local game = require("game_state")

local stopSaving = game:subscribe(function(state)
  local contents = encodeSave(state) -- Your JSON/Lua/binary serializer.
  local ok, message = love.filesystem.write("save.json", contents)
  if not ok then
    print("save failed", message)
  end
end)

Load and migrate persisted data before constructing or replacing the store:

local defaults = { score = 0, paused = false }
local saved = loadAndMigrateSave("save.json")
local game = store(saved or defaults)

Runtime And Overrides¶

store({...}) lowers to require("tuastore"). tua build writes the bundled tuastore.lua beside generated Lua only when the helper is used. A project-provided tuastore.lua is never overwritten, so compatible custom implementations can replace the bundled runtime.