tm.paging

Fetches a large dataset from the server to the client one page at a time. Needs tm.callback (the server registers, the client awaits). The server side is registerCallback, the client side is loadDataset.

Server: tm.paging.registerCallback(callbackName, options)

tm.paging.registerCallback('myres:getItems', {
    getItems = function(source, ...) return items end,                  -- required: the whole dataset (any table)
    map = function(item, source, ...) return { id = item.id } end,       -- required: per item, return nil to drop it
    sort = function(a, b) return a.name < b.name end,                    -- optional
    before = function(source) end,                                       -- optional: runs on every page request, throw to refuse
    minPageSize = 25, maxPageSize = 500, defaultPageSize = 150,          -- optional
    presorted = false, snapshotMs = 0,                                   -- optional, see below
})

The callback receives (source, cursor, pageSize, ...) from the client and returns { items, cursor, nextCursor, total }. It is registered through tm.callback with kind 'paged'.

Option	Meaning
getItems(source, ...)	Returns the dataset. Extra arguments are whatever the client passed to loadDataset.
map(item, source, ...)	Shapes each item sent to the client.
sort(a, b)	Comparator applied to a copy before paging.
before(source)	Pre-flight hook.
minPageSize, maxPageSize, defaultPageSize	The client's requested size is clamped to these. Defaults 25, 500, 150.
presorted	getItems returns an ordered array that is not mutated: read it in place and skip the per-page copy and sort.
snapshotMs	A page after the first reads the item list the first page built for that source, if it is at most this many ms old, instead of calling getItems again. A whole-dataset load then costs one getItems (one query) instead of one per page, and the pages are consistent with each other. The first page always rebuilds, so a refresh after a write is never stale. Only for callbacks with no extra arguments. The snapshot is dropped after the last page and when the player leaves.

Client: tm.paging.loadDataset(callbackName, pageSize?, map?, ...)

local items, ok, total, complete = tm.paging.loadDataset('myres:getItems', 100, function(item, index)
    return item   -- return nil to drop an item
end, extraArg)

Loads every page and returns one array. It must run in a thread.

Return	Meaning
items	All items, or nil when the first page never arrived.
ok	false when the first page failed (after one retry), so the caller can fall back.
total	The server's item count, when it sent one.
complete	false when loading stopped before the last page (items holds what arrived). A failed later page is retried twice before giving up.

Extra arguments after map are forwarded to the server callback.