Navigation.create
luastra/navigationNavigation.create(options: Options): Stack
Creates a named-route stack initialized from Navigation.Options and exposes operations such as current, push, replace, back, encode, and restore. The stack is ordinary application state and survives renders when created once at module scope.
Before you use it
Add luastra/navigation to this module's dependencies in luastra.json, then import it with require("luastra/navigation"). No host capability is required for in-memory navigation. Browser URL/history synchronization additionally needs luastra/host and navigation.history.
How it fits
The operation updates or creates application-owned navigation state synchronously. Keep stacks and compilers outside app.render, inspect every result.success field, then render from the accepted current entry.
When to use it
Use Navigation.create for an application whose routes can be represented by stable names and optional state tokens without typed path parameters. Render from stack.current() and mutate the same stack in app.handle.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| options | Options | Allowed route names, initial route, and optional restoration settings for the named stack. |
| options.routes | {string} (1..64) | Unique lowercase route names admitted by this stack. |
| options.initial | string | One admitted route used as the initial stack entry. |
| options.maximumDepth | integer (1..32)? | Optional history-depth bound; defaults to 32. |
Returns
Stack — a stateful named-route stack; create it once and call its public methods across renders.
What happens next
A validated compiler, stack, decision, or result record; host history changes only when the application requests them separately.
Failures and fixes
Invalid definitions, unknown routes, malformed parameters, excessive history depth, or incompatible snapshots return bounded errors or fail construction. Navigation result records use success:boolean with optional fields, so verify the field you need after checking success.
Availability
Public-source alpha API in 0.5.0-alpha; URL integration is a separate host capability.
Focused example
local Navigation = require("luastra/navigation")
local navigation = Navigation.create {
routes = { "home", "game" },
initial = "home",
}
navigation.push("game")