State.DecodeResult
luastra/stateState.DecodeResult is a discriminated union covering successful output and bounded failure. Branching on success narrows the value to the correct exported record and makes error handling explicit.
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
The type describes string fields, migration functions, or tagged decode/migration results.
When to use it
Use State.DecodeResult at the boundary where untrusted or versioned input is decoded. Branch on result.success before reading value or error so both outcomes remain explicit and type-safe.
Fields or definition
| Parameter | Type / values | Description |
|---|---|---|
| definition | DecodeSuccess | DecodeFailure | Exact alias, union, or callable contract represented by State.DecodeResult. |
Error codes
This is the complete closed vocabulary emitted by the named operation in this Source SDK contract.
| Code | When it occurs |
|---|---|
| empty | The encoded state is empty or not a string. |
| too_large | The encoded state exceeds 4096 bytes. |
| invalid_expected_version | expectedVersion is not an integer from 1 through 999. |
| malformed | The version prefix or field structure is malformed. |
| unsupported_version | The encoded version differs from expectedVersion. |
| too_many_fields | The encoded state contains more than 32 fields. |
| invalid_field | A field name is invalid or duplicated. |
| invalid_encoding | A field contains invalid or non-canonical percent encoding. |
SDK type flow
Produced by
Consumed by the SDK
What happens next
A checked snapshot or result annotation.
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.
Exact declaration
export type DecodeResult = DecodeSuccess | DecodeFailure