State.MigrationResult
luastra/stateState.MigrationResult 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.MigrationResult 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 | MigrationSuccess | MigrationFailure | Exact alias, union, or callable contract represented by State.MigrationResult. |
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 source state is empty or not a string. |
| too_large | The encoded source state exceeds 4096 bytes. |
| invalid_target_version | targetVersion is not an integer from 1 through 999. |
| invalid_migrations | The migration collection is not a table. |
| malformed | The source version prefix is missing or invalid. |
| newer_version | The source version is newer than the requested target. |
| too_many_migrations | The migration would require more than 32 steps. |
| missing_migration | No migration function exists for the current version. |
| migration_failed | A migration function raised an error. |
| invalid_migration | A migration returned, encoded, or verified an invalid replacement. |
SDK type flow
Produced by
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 MigrationResult = MigrationSuccess | MigrationFailure