State.migrate
luastra/stateState.migrate(value: string, targetVersion: number, migrationsValue: any): MigrationResult
Decodes a snapshot and applies explicitly ordered Migration functions until it reaches the requested target version. The result records structured failure if a step is missing, invalid, or does not advance correctly.
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.migrate during application startup when released versions must preserve user state across schema changes. Keep every migration deterministic, test each supported starting version, and never silently reinterpret unknown future data.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| value | string | Untrusted serialized snapshot that may use an older supported version. |
| targetVersion | number | Version the migration chain must reach. |
| migrationsValue | any | Map from each supported source version to its deterministic next-version function. |
Returns
MigrationResult — the exact MigrationResult value declared by the SDK contract.
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 result = State.migrate(oldSnapshot, 2, { [1] = function(fields) return { score = fields.score or "0" } end })