Collection.State
luastra/collectionCollection.State 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.State 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 |
|---|---|---|
| begin | (direction: Direction, requestId: number, refreshCursor: string?) -> Ticket | Callable begin member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| resolve | (ticket: Ticket, page: Page<T>) -> ResolveResult | Callable resolve member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| reject | (ticket: Ticket, error: Error) -> boolean | Callable reject member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| cancel | (ticket: Ticket?) -> boolean | Callable cancel member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| setAnchor | (key: string?) -> boolean | Callable setAnchor member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| insert | (item: T, edge: ("start" | "end")?) -> boolean | Callable insert member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| replace | (key: string, item: T) -> boolean | Callable replace member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| remove | (key: string) -> boolean | Callable remove member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| invalidate | () -> () | Callable invalidate member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| reset | () -> () | Callable reset member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
| snapshot | () -> Snapshot<T> | Callable snapshot member exposed by Collection.State; invoke it through the owning contract rather than replacing internal state. |
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 State<T> = {
begin: (direction: Direction, requestId: number, refreshCursor: string?) -> Ticket,
resolve: (ticket: Ticket, page: Page<T>) -> ResolveResult,
reject: (ticket: Ticket, error: Error) -> boolean,
cancel: (ticket: Ticket?) -> boolean,
setAnchor: (key: string?) -> boolean,
insert: (item: T, edge: ("start" | "end")?) -> boolean,
replace: (key: string, item: T) -> boolean,
remove: (key: string) -> boolean,
invalidate: () -> (),
reset: () -> (),
snapshot: () -> Snapshot<T>,
}