State.decode
luastra/stateState.decode(value: string, expectedVersion: number): DecodeResult
Parses a snapshot string, verifies its structure and version, and returns a discriminated DecodeResult. A version mismatch or malformed value remains a normal failure branch rather than becoming trusted state.
Before you use it
Add luastra/state to this module's dependencies in luastra.json, then import it with require("luastra/state"). No capability is required for encoding, decoding, or migration. Persistence additionally needs luastra/host plus storage.get and storage.set.
How it fits
State operations run synchronously over bounded string fields. Encode before storage; after a read, decode or migrate and branch on success before mutating trusted application state.
When to use it
Use State.decode after reading storage when only the current snapshot version is accepted. Branch on success before restoring fields; use State.migrate when older admitted versions must be upgraded.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| value | string | Untrusted serialized snapshot string read from storage or another boundary. |
| expectedVersion | number | Only version accepted by this direct decode operation. |
Returns
DecodeResult — a discriminated decode result; branch on success before reading decoded fields or failure data.
What happens next
A deterministic encoded snapshot or a tagged success/failure result.
Failures and fixes
Malformed data, wrong versions, missing migration steps, excessive size, or non-string fields remain explicit failure branches. Do not silently replace corrupt security- or domain-sensitive values with defaults.
Availability
Public-source alpha API in 0.5.0-alpha; persistence support is host-dependent.
Focused example
local State = require("luastra/state")
local restored = State.decode(snapshot, 1)
if restored.success then score = tonumber(restored.fields.score) or 0 endContinue with a complete recipe
This checked recipe uses State.decode inside complete authored files with the required manifest, test, and run steps.
Open persist and restore state recipe