dataSource

TTL + gated cached data fetcher. Used by tools that pull live data from the engine at a slower cadence than the UI rebuilds. A closed gate returns the last cached value WITHOUT calling the fetch function; within TTL, the cached value is returned directly. Errors from the fetcher are swallowed by default (last value preserved) and surfaced through the optional onError hook.

The module table itself is callable as a shorthand for .create.

Exports

• M.create(fetchFn: () -> any, opts: Opts?) -> Source — build a new source. Also reachable as M(fetchFn, opts).
• M.invalidate(key: string) — force a re-fetch on the next read for a registered key.
• M.reset() — wipe the registry; release retained values.
• M._seedForTest(key: string, value: any) -> Source? — test hook: install a value without invoking the fetcher.
• M._peekForTest(key: string) -> Source? — test hook: look up a source by key.

Per-instance methods (on Source):

• source:read() -> value — read with TTL + gate semantics.
• source() — callable shorthand, equivalent to source:read().
• source:invalidate() — clear cached value and timestamp.
• source.version: number — monotonic counter bumped on every successful fetch.

Types:

• Opts = { ttl: number?, gate: (() -> boolean)?, key: string?, onError: ((any) -> ())? }
• Source — instance carrying fetchFn, ttl, gate, onError, key, version, and the internal _value / _t cache slots.

Usage

local DataSource = require("@builtin::modules.zui.dataSource")

local entities = DataSource(function()
    return wld.list()
end, { ttl = 0.2, key = "entities:list" })

local list = entities()                 -- callable shorthand
local same = entities:read()            -- explicit form
DataSource.invalidate("entities:list")  -- force re-fetch

Notes

• TTL 0 means "always re-fetch"; the cache slot still holds the last value so a closed gate or a fetch error returns it.
• A closed gate (gate() returns false) skips the fetch entirely and returns the cached value as-is — useful for visibility gating.
• Fetcher errors are swallowed (cached value preserved) and routed through onError(err) when set.
• Auto-allocated keys are namespaced under "zui:dataSource:<n>". Explicit keys are preferred so invalidate and the test hooks have a stable handle.