Skip to main content

LiteralSchema

Accepts exactly one value, compared with ==. Use it where a field may only hold a specific constant, and combine several through ObjectSchema fields to describe a tagged shape. 

local Consented = v.literal(true)
local Kind = v.literal("player")

Consented:parse(true)  --> true
Consented:parse(false) --> errors: expected true, got false
Kind:parse("npc")      --> errors: expected "player", got "npc"

Properties​

value​

This item is read only and cannot be modified. Read OnlyReflection
</>
LiteralSchema.value: T

The one value this schema accepts.

isOptional​

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

Always false.

access​

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

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

Functions​

safeParse​

Parsing
</>
LiteralSchema:safeParse(value: unknown) → Result<T>

Validates value without throwing.

parse​

Parsing
</>
LiteralSchema:parse(value: unknown) → T

Validates value and returns it, throwing on failure.

Errors

TypeDescription
"expected ..."Thrown when `value` is anything else

optional​

Wrapper
</>
LiteralSchema:optional() → OptionalSchema<T>

Wraps this schema so that nil is also accepted.

default​

Wrapper
</>
LiteralSchema:default(
fallback: T--

Value used when parsing nil

) → DefaultSchema<T>

Wraps this schema so that nil yields fallback instead of failing.

defaultWith​

Wrapper
</>
LiteralSchema:defaultWith(
produce: () → T--

Builds the value used when parsing nil

) → DefaultSchema<T>

Like :default, but calls produce on every parse.

readonly​

Wrapper
</>
LiteralSchema:readonly() → ReadonlySchema<T>

Wraps this schema so that a field using it is typed read. Pairing it with a singleton annotation gives an object a tag that cannot be overwritten after parsing.

writeonly​

Wrapper
</>
LiteralSchema:writeonly() → WriteonlySchema<T>

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

Show raw api
{
    "functions": [
        {
            "name": "safeParse",
            "desc": "Validates `value` without throwing.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Result<T>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "source": {
                "line": 2088,
                "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` is anything else"
                }
            ],
            "source": {
                "line": 2108,
                "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": 2126,
                "path": "src/init.luau"
            }
        },
        {
            "name": "default",
            "desc": "Wraps this schema so that `nil` yields `fallback` instead of failing.\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": 2141,
                "path": "src/init.luau"
            }
        },
        {
            "name": "defaultWith",
            "desc": "Like `:default`, but calls `produce` on every parse.\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": 2158,
                "path": "src/init.luau"
            }
        },
        {
            "name": "readonly",
            "desc": "Wraps this schema so that a field using it is typed `read`. Pairing it\nwith a singleton annotation gives an object a tag that cannot be\noverwritten after parsing.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReadonlySchema<T>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 2174,
                "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": 2188,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "value",
            "desc": "The one value this schema accepts.\n\t",
            "lua_type": "T",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2045,
                "path": "src/init.luau"
            }
        },
        {
            "name": "isOptional",
            "desc": "Always `false`.\n\t",
            "lua_type": "boolean",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2055,
                "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": 2065,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "LiteralSchema",
    "desc": "Accepts exactly one value, compared with `==`. Use it where a field may only\nhold a specific constant, and combine several through [ObjectSchema] fields\nto describe a tagged shape.\n\n```lua\nlocal Consented = v.literal(true)\nlocal Kind = v.literal(\"player\")\n\nConsented:parse(true)  --> true\nConsented:parse(false) --> errors: expected true, got false\nKind:parse(\"npc\")      --> errors: expected \"player\", got \"npc\"\n```",
    "source": {
        "line": 2010,
        "path": "src/init.luau"
    }
}