Skip to main content

TupleSchema

Validates a fixed sequence where each position has its own schema. Use it for packed argument lists and other positional payloads, where ArraySchema would only let you say that every element is the same shape.

Like ArraySchema, the input is returned untouched unless a position fills a value in, in which case it is shallow copied first. 

local Waypoint = v.tuple({ v.string(), v.number():integer() })

Waypoint:parse({ "spawn", 3 }) --> { "spawn", 3 }
Waypoint:parse({ "spawn" })    --> errors: [2]: expected number, got nil
Waypoint:parse({ "a", 1, 2 })  --> errors: expected a tuple of 2 values, got 3

A position whose schema is optional or has a default may be left off the end, since Lua cannot tell a trailing nil from a shorter list: 

local Ping = v.tuple({ v.string(), v.number():default(0) })

Ping:parse({ "hello" }) --> { "hello", 0 }

Properties​

minimum​

This item is read only and cannot be modified. Read OnlyReflection
</>
TupleSchema.minimum: number?

Always nil. How few values a tuple accepts depends on how many of its trailing positions tolerate nil, so there is no single number.

maximum​

This item is read only and cannot be modified. Read OnlyReflection
</>
TupleSchema.maximum: number?

The number of positions, which is the most values this schema accepts.

isOptional​

This item is read only and cannot be modified. Read OnlyReflection
</>
TupleSchema.isOptional: boolean

Always false.

access​

This item is read only and cannot be modified. Read OnlyReflection
</>
TupleSchema.access: "readwrite"

Always "readwrite". Chain :readonly() or :writeonly() to change it.

Functions​

safeParse​

Parsing
</>
TupleSchema:safeParse(value: unknown) → Result<{T}>

Validates each position against its own schema, reporting failures with the index in the issue path.

parse​

Parsing
</>
TupleSchema:parse(value: unknown) → {T}

Validates value and returns it, throwing on failure.

Errors

TypeDescription
"expected ..."Thrown when `value` fails validation

optional​

Wrapper
</>
TupleSchema:optional() → OptionalSchema<{T}>

Wraps this schema so that nil is also accepted.

default​

Wrapper
</>
TupleSchema:default(
fallback: {T}--

Value used when parsing nil

) → DefaultSchema<{T}>

Wraps this schema so that nil yields fallback instead of failing. Prefer passing a function, since a constant table would be shared by every parse.

defaultWith​

Wrapper
</>
TupleSchema:defaultWith(
produce: () → {T}--

Builds the value used when parsing nil

) → DefaultSchema<{T}>

Like :default, but calls produce on every parse instead of reusing one value. Prefer it here, since a single table would otherwise be shared by every caller and mutable through any of them.

The produced value is validated each time.

readonly​

Wrapper
</>
TupleSchema:readonly() → ReadonlySchema<{T}>

Wraps this schema so that a field using it is typed read.

writeonly​

Wrapper
</>
TupleSchema:writeonly() → WriteonlySchema<{T}>

Wraps this schema so that a field using it is typed write.

Show raw api
{
    "functions": [
        {
            "name": "safeParse",
            "desc": "Validates each position against its own schema, reporting failures with\nthe index in the issue path.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Result<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "source": {
                "line": 2617,
                "path": "src/init.luau"
            }
        },
        {
            "name": "parse",
            "desc": "Validates `value` and returns it, throwing on failure.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ T }"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "errors": [
                {
                    "lua_type": "\"expected ...\"",
                    "desc": "Thrown when `value` fails validation"
                }
            ],
            "source": {
                "line": 2691,
                "path": "src/init.luau"
            }
        },
        {
            "name": "optional",
            "desc": "Wraps this schema so that `nil` is also accepted.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "OptionalSchema<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2719,
                "path": "src/init.luau"
            }
        },
        {
            "name": "default",
            "desc": "Wraps this schema so that `nil` yields `fallback` instead of failing.\nPrefer passing a function, since a constant table would be shared by\nevery parse.\n\t",
            "params": [
                {
                    "name": "fallback",
                    "desc": "Value used when parsing `nil`",
                    "lua_type": "{ T }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DefaultSchema<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2736,
                "path": "src/init.luau"
            }
        },
        {
            "name": "defaultWith",
            "desc": "Like `:default`, but calls `produce` on every parse instead of reusing\none value. Prefer it here, since a single table would otherwise be\nshared by every caller and mutable through any of them.\n\nThe produced value is validated each time.\n\t",
            "params": [
                {
                    "name": "produce",
                    "desc": "Builds the value used when parsing `nil`",
                    "lua_type": "() -> { T }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DefaultSchema<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2757,
                "path": "src/init.luau"
            }
        },
        {
            "name": "readonly",
            "desc": "Wraps this schema so that a field using it is typed `read`.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReadonlySchema<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2771,
                "path": "src/init.luau"
            }
        },
        {
            "name": "writeonly",
            "desc": "Wraps this schema so that a field using it is typed `write`.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "WriteonlySchema<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2785,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "minimum",
            "desc": "Always `nil`. How few values a tuple accepts depends on how many of its\ntrailing positions tolerate `nil`, so there is no single number.\n\t",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2575,
                "path": "src/init.luau"
            }
        },
        {
            "name": "maximum",
            "desc": "The number of positions, which is the most values this schema accepts.\n\t",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2585,
                "path": "src/init.luau"
            }
        },
        {
            "name": "isOptional",
            "desc": "Always `false`.\n\t",
            "lua_type": "boolean",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2595,
                "path": "src/init.luau"
            }
        },
        {
            "name": "access",
            "desc": "Always `\"readwrite\"`. Chain `:readonly()` or `:writeonly()` to change it.\n\t",
            "lua_type": "\"readwrite\"",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2605,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "TupleSchema",
    "desc": "Validates a fixed sequence where each position has its own schema. Use it\nfor packed argument lists and other positional payloads, where [ArraySchema]\nwould only let you say that every element is the same shape.\n\nLike [ArraySchema], the input is returned untouched unless a position fills\na value in, in which case it is shallow copied first.\n\n```lua\nlocal Waypoint = v.tuple({ v.string(), v.number():integer() })\n\nWaypoint:parse({ \"spawn\", 3 }) --> { \"spawn\", 3 }\nWaypoint:parse({ \"spawn\" })    --> errors: [2]: expected number, got nil\nWaypoint:parse({ \"a\", 1, 2 })  --> errors: expected a tuple of 2 values, got 3\n```\n\nA position whose schema is optional or has a default may be left off the\nend, since Lua cannot tell a trailing `nil` from a shorter list:\n\n```lua\nlocal Ping = v.tuple({ v.string(), v.number():default(0) })\n\nPing:parse({ \"hello\" }) --> { \"hello\", 0 }\n```",
    "source": {
        "line": 2545,
        "path": "src/init.luau"
    }
}