Collection.new

luastra/collection

Collection.new(options: Options<T>): State<T>

Creates a bounded bidirectional page controller whose snapshots expose a flat ordered item window. Stable keys, tickets, cursors, anchor-aware eviction, duplicate rejection, edge-specific failures, and maximum page and item counts make long feeds predictable.

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.new creates one long-lived controller. begin admits one page request at a time, resolve validates its exact ticket and page, and the controller evicts distant pages while preserving a flat snapshot and visible anchor when possible.

When to use it

Use Collection.new for timelines, catalogues, messages, logs, or any collection that can outgrow memory. Load pages from explicit events or viewport signals, keep an anchor near the user's position, and render snapshot.items with their stable keys.

Parameters

Parameter	Type / values	Description
options	Options<T>	Checked options argument accepted by Collection.new.

Returns

State<T> — the exact State<T> value declared by the SDK contract.

What happens next

A bounded bidirectional collection window ready to feed UI.List or another renderer without retaining every item ever loaded.

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.

Focused example

local Collection = require("luastra/collection")

local feed = Collection.new {
    key = function(item: { id: string }): string
        return item.id
    end,
    maxItems = 200,
    maxPages = 8,
}

local ticket = feed.begin("initial", requestId)
feed.resolve(ticket, {
    items = pageItems,
    nextCursor = nextCursor,
})

local snapshot = feed.snapshot()

Complete inventory

View all pages in Bounded paged collections

Source alpha