Collection.Snapshot
luastra/collectionCollection.Snapshot is an exported, statically checked data contract of luastra/collection. Its exact declaration documents the fields or alternatives accepted at the module boundary and is erased after Luau analysis.
Before you use it
Add luastra/collection to this module's dependencies in luastra.json, then import it with require("luastra/collection"). Choose a stable bounded key for every item and explicit maxItems, maxPages, and maxPageItems values appropriate to the screen. Provider cursors remain application state and must never be used as UI node IDs.
How it fits
Collection types describe pages, directions, tickets, bounded snapshots, results, and the state controller contract.
When to use it
Use Collection.Snapshot when annotating values that cross the public luastra/collection boundary or when exporting helpers built on that module. The type documents the exact checked shape and prevents unrelated tables from being substituted accidentally.
Fields or definition
| Parameter | Type / values | Description |
|---|---|---|
| status | Status | Checked status field of Collection.Snapshot; its exact admitted type is Status. |
| items | { T } | Checked items field of Collection.Snapshot; its exact admitted type is { T }. |
| keys | { string } | Checked keys field of Collection.Snapshot; its exact admitted type is { string }. |
| loading | Direction? | Checked loading field of Collection.Snapshot; its exact admitted type is Direction?. |
| error | Error? | Bounded failure information, or nil on the successful branch. |
| previousError | Error? | Checked previousError field of Collection.Snapshot; its exact admitted type is Error?. |
| nextError | Error? | Checked nextError field of Collection.Snapshot; its exact admitted type is Error?. |
| hasPrevious | boolean | Checked hasPrevious field of Collection.Snapshot; its exact admitted type is boolean. |
| hasNext | boolean | Checked hasNext field of Collection.Snapshot; its exact admitted type is boolean. |
| anchorKey | string? | Checked anchorKey field of Collection.Snapshot; its exact admitted type is string?. |
| generation | number | Checked generation field of Collection.Snapshot; its exact admitted type is number. |
| invalidated | boolean | Checked invalidated field of Collection.Snapshot; its exact admitted type is boolean. |
| pageCount | number | Checked pageCount field of Collection.Snapshot; its exact admitted type is number. |
What happens next
A checked page-window annotation for cursor-based ordered data.
Failures and fixes
Duplicate or malformed keys, oversized pages, repeated cursors, stale tickets, or invalid bounds are rejected without silently corrupting order. Edge failures remain separate so the existing window stays usable while the user retries only the failed direction.
Availability
Public-source alpha collection API in 0.5.0-alpha; fetching and viewport triggers remain explicit application and host concerns.
Exact declaration
export type Snapshot<T> = {
status: Status,
items: { T },
keys: { string },
loading: Direction?,
error: Error?,
previousError: Error?,
nextError: Error?,
hasPrevious: boolean,
hasNext: boolean,
anchorKey: string?,
generation: number,
invalidated: boolean,
pageCount: number,
}