Skip to main content

ArraySchema

Validates a contiguous array where every element matches one inner schema. Tables carrying non-array keys are rejected outright.

The array you pass in is returned untouched unless an element fills a value in, which only a nested DefaultSchema does. In that case the input is shallow copied and the filled values written to the copy, so parsing never modifies what it was given and never allocates a copy it does not need. 

local Scores = v.array(v.number():integer()):max(4)

Properties​

minimum​

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

Fewest elements this schema accepts, or nil if it is unbounded. Set by ArraySchema:min.

maximum​

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

Most elements this schema accepts, or nil if it is unbounded. Set by ArraySchema:max.

isOptional​

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

Always false.

access​

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

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

Functions​

safeParse​

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

Validates every element, reporting each failure with its index in the issue path.

parse​

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

Validates value and returns it, throwing on failure.

Errors

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

min​

Refinement
</>
ArraySchema:min(
n: number--

Minimum element count, inclusive

) → ArraySchema<T>

Requires the array to hold at least n elements.

max​

Refinement
</>
ArraySchema:max(
n: number--

Maximum element count, inclusive

) → ArraySchema<T>

Requires the array to hold at most n elements.

optional​

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

Wraps this schema so that nil is also accepted.

default​

Wrapper
</>
ArraySchema: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 array would be shared by every parse.

defaultWith​

Wrapper
</>
ArraySchema: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
</>
ArraySchema:readonly() → ReadonlySchema<{T}>

Wraps this schema so that a field using it is typed read. The array itself stays mutable; it is the field that cannot be reassigned.

writeonly​

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

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

Show raw api
{
    "functions": [
        {
            "name": "safeParse",
            "desc": "Validates every element, reporting each failure with its index in the\nissue path.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Result<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "source": {
                "line": 2292,
                "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": 2374,
                "path": "src/init.luau"
            }
        },
        {
            "name": "min",
            "desc": "Requires the array to hold at least `n` elements.\n\t",
            "params": [
                {
                    "name": "n",
                    "desc": "Minimum element count, inclusive",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ArraySchema<T>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Refinement"
            ],
            "source": {
                "line": 2403,
                "path": "src/init.luau"
            }
        },
        {
            "name": "max",
            "desc": "Requires the array to hold at most `n` elements.\n\t",
            "params": [
                {
                    "name": "n",
                    "desc": "Maximum element count, inclusive",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ArraySchema<T>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Refinement"
            ],
            "source": {
                "line": 2423,
                "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": 2442,
                "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 array 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": 2459,
                "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": 2480,
                "path": "src/init.luau"
            }
        },
        {
            "name": "readonly",
            "desc": "Wraps this schema so that a field using it is typed `read`. The array\nitself stays mutable; it is the field that cannot be reassigned.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReadonlySchema<{ T }>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2495,
                "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": 2509,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "minimum",
            "desc": "Fewest elements this schema accepts, or `nil` if it is unbounded. Set\nby [ArraySchema:min].\n\t",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2249,
                "path": "src/init.luau"
            }
        },
        {
            "name": "maximum",
            "desc": "Most elements this schema accepts, or `nil` if it is unbounded. Set by\n[ArraySchema:max].\n\t",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2260,
                "path": "src/init.luau"
            }
        },
        {
            "name": "isOptional",
            "desc": "Always `false`.\n\t",
            "lua_type": "boolean",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2270,
                "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": 2280,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "ArraySchema",
    "desc": "Validates a contiguous array where every element matches one inner schema.\nTables carrying non-array keys are rejected outright.\n\nThe array you pass in is returned untouched unless an element fills a value\nin, which only a nested [DefaultSchema] does. In that case the input is\nshallow copied and the filled values written to the copy, so parsing never\nmodifies what it was given and never allocates a copy it does not need.\n\n```lua\nlocal Scores = v.array(v.number():integer()):max(4)\n```",
    "source": {
        "line": 2212,
        "path": "src/init.luau"
    }
}