Parser
Defined in: src/createParser.ts:175
Parser interface with type-safe parse methods.
Schemas are arktype object defs, validated at compile time by type.validate IN THE PARSER’S SCOPE on EVERY entry point — a typo’d leaf like { x: “numbr” } errors at the leaf, while an alias leaf like { created: “Timestamp” } resolves when the parser was created with { scope: { Timestamp: … } }. The same scope drives literal-mode parsing (identifier/path types) and runtime compilation.
History note: parse/evaluate could not carry type.validate before the 2026-07 rework — combined with their deferred-conditional input parameter, inference was METASTABLE (declaration-order-dependent). The rework’s depth reductions moved the shape off the instantiation edge; re-tested 2026-07-07 across 8 declaration-order permutations × TS 5.7/5.9/6.0, warm and cold (pinned in design-claims.typetest.ts). evaluate’s values stay NoInfer-wrapped — WITHOUT it, TS inverts the mapped type inside type.infer and silently unions the values argument into TSchema (also pinned there).
Type Parameters
Section titled “Type Parameters”TGrammar
Section titled “TGrammar”TGrammar extends Grammar
TNodes
Section titled “TNodes”TNodes extends readonly NodeSchema[]
$
$ extends object = { }
Properties
Section titled “Properties”
readonlynodes:TNodes
Defined in: src/createParser.ts:255
The node schemas used to create this parser
Methods
Section titled “Methods”parse()
Section titled “parse()”parse<
TInput,TSchema>(input,schema):Parse<TGrammar,TInput,Context<TSchema,$>>
Defined in: src/createParser.ts:188
Parse a string literal, validated at compile time.
The input must be a literal that FULLY parses against the grammar — anything else is a compile-time error. For runtime-provided strings, use safeParse. Throws StringentParseError if the compile-time check was bypassed and the input is invalid.
Type Parameters
Section titled “Type Parameters”TInput
Section titled “TInput”TInput extends string
TSchema
Section titled “TSchema”TSchema extends SchemaShape
Parameters
Section titled “Parameters”ValidatedInput<TGrammar, TInput, Context<TSchema, $>>
schema
Section titled “schema”[TSchema] extends [" anyOrNever"] ? TSchema : TSchema extends OptionalPropertyDefinition ? "Optional definitions like 'string?' are only valid as properties in an object or tuple" : isDefaultable<TSchema, $, bindThis<TSchema>> extends true ? "Defaultable definitions like 'number = 0' are only valid as properties in an object or tuple" : validateInnerDefinition<TSchema, $, bindThis<TSchema>>
Returns
Section titled “Returns”Parse<TGrammar, TInput, Context<TSchema, $>>
safeParse()
Section titled “safeParse()”safeParse<
TInput,TSchema>(input,schema):SafeParseResult<AstFor<TGrammar,TInput,TSchema,$>>
Defined in: src/createParser.ts:202
Parse any string (including runtime-provided input).
Requires the whole input to be consumed. NEVER throws: invalid input returns a structured error with position/expected/found; an invalid schema (a programmer error, normally caught at compile time by type.validate) returns { success: false, error: { code: “INVALID_SCHEMA” } }.
Type Parameters
Section titled “Type Parameters”TInput
Section titled “TInput”TInput extends string
TSchema
Section titled “TSchema”TSchema extends SchemaShape
Parameters
Section titled “Parameters”TInput
schema
Section titled “schema”[TSchema] extends [" anyOrNever"] ? TSchema : TSchema extends OptionalPropertyDefinition ? "Optional definitions like 'string?' are only valid as properties in an object or tuple" : isDefaultable<TSchema, $, bindThis<TSchema>> extends true ? "Defaultable definitions like 'number = 0' are only valid as properties in an object or tuple" : validateInnerDefinition<TSchema, $, bindThis<TSchema>>
Returns
Section titled “Returns”SafeParseResult<AstFor<TGrammar, TInput, TSchema, $>>
evaluate()
Section titled “evaluate()”evaluate<
TInput,TSchema>(input,schema,values):EvaluateResult<TGrammar,TInput,TSchema,$>
Defined in: src/createParser.ts:213
Parse a string literal and evaluate it against runtime values.
Node eval() functions (from defineNode) compute the result. The values object is validated against the schema before evaluation.
Type Parameters
Section titled “Type Parameters”TInput
Section titled “TInput”TInput extends string
TSchema
Section titled “TSchema”TSchema extends SchemaShape
Parameters
Section titled “Parameters”ValidatedInput<TGrammar, TInput, Context<TSchema, $>>
schema
Section titled “schema”[TSchema] extends [" anyOrNever"] ? TSchema : TSchema extends OptionalPropertyDefinition ? "Optional definitions like 'string?' are only valid as properties in an object or tuple" : isDefaultable<TSchema, $, bindThis<TSchema>> extends true ? "Defaultable definitions like 'number = 0' are only valid as properties in an object or tuple" : validateInnerDefinition<TSchema, $, bindThis<TSchema>>
values
Section titled “values”NoInfer<inferDefinition<TSchema, $, bindThis<TSchema>>>
Returns
Section titled “Returns”EvaluateResult<TGrammar, TInput, TSchema, $>
evaluateAst()
Section titled “evaluateAst()”evaluateAst<
TAst>(ast,values):InferOfDef<TAst["outputSchema"]>
Defined in: src/createParser.ts:226
Evaluate an already-parsed AST against runtime values. Use with safeParse for dynamic input.
Type Parameters
Section titled “Type Parameters”TAst extends object
Parameters
Section titled “Parameters”TAst
values
Section titled “values”EvaluationValues
Returns
Section titled “Returns”InferOfDef<TAst["outputSchema"]>
compile()
Section titled “compile()”compile<
TInput,TSchema>(input,schema,options?):CompiledRule<TGrammar,TInput,TSchema,$>
Defined in: src/createParser.ts:248
Compile a rule into an arktype Type (D12) — the ecosystem bridge.
A boolean-output rule becomes a PREDICATE Type: it validates the
values object against the schema (refinements included), evaluates
the rule, and rejects with an ArkErrors entry at options.path when
the rule is false. Any other rule becomes a MORPH Type: values in,
evaluated result out. Either way the result is a real arktype Type —
a Standard Schema — so it plugs into react-hook-form, tRPC, hono, …
.in is the values contract; predicate rules carry a predicate node,
so JSON Schema export needs the fallback:
rule.in.toJsonSchema({ fallback: { predicate: (ctx) => ctx.base } }).
Unlike parse/evaluate, dynamic strings ARE accepted (rules often live in config); invalid input throws StringentParseError at compile time — literal inputs additionally get precise compile-time typing.
Type Parameters
Section titled “Type Parameters”TInput
Section titled “TInput”TInput extends string
TSchema
Section titled “TSchema”TSchema extends SchemaShape
Parameters
Section titled “Parameters”TInput
schema
Section titled “schema”[TSchema] extends [" anyOrNever"] ? TSchema : TSchema extends OptionalPropertyDefinition ? "Optional definitions like 'string?' are only valid as properties in an object or tuple" : isDefaultable<TSchema, $, bindThis<TSchema>> extends true ? "Defaultable definitions like 'number = 0' are only valid as properties in an object or tuple" : validateInnerDefinition<TSchema, $, bindThis<TSchema>>
options?
Section titled “options?”Returns
Section titled “Returns”CompiledRule<TGrammar, TInput, TSchema, $>