Log inGet started
Package

zui.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

state

Reactive state container for Z.app. Backs the Layer 3 example in docs/specs/ui-v3-architecture.md — state:default(...), state.nodes, state:set("size", n), etc. Writes via the data-store path (state.foo = bar) or the method path (state:set("foo", bar)) both auto-mark the owning App dirty.

Exports

  • State.create(initial: { [string]: any }?, app: App?) -> StateInstance — make a new container.
  • Instance methods (also reachable via reactive state.foo = bar writes):
    • state:default(initial) — write only keys not already present; idempotent. Does NOT mark dirty.
    • state:get(key) — typed read of a data-store key.
    • state:set(key, value) — write one key; marks dirty on change.
    • state:update(updates) — bulk write; single dirty-mark per call.
    • state:all() — return the raw data-store table.

Types:

  • App = { markDirty: ((App) -> ())? } — minimum owning-App contract.
  • StateInstance — the metatable-bound container; supports state.foo field access in addition to the methods.

Usage

local State = require("@builtin::modules.zui.state")
local s = State.create({ count = 0 }, app)
s:default({ size = 10 })   -- idempotent, no dirty mark
s.nodes = { ... }          -- reactive __newindex, marks dirty
s:set("count", 5)          -- method path, marks dirty

Notes

  • The methods table is consulted by __index BEFORE the data store, so state:default resolves to the method even if a default data key exists.
  • :default is a setup-time merge and intentionally does NOT mark the App dirty — it's safe to call inside an App.create builder.
  • :update collapses multiple key writes into a single dirty-mark; use it in hot loops where the per-key __newindex path would mark dirty on every assignment.