Repository navigation
Fluent builder API for pattern definitions with compile-time validation - #7
Conversation
Evaluation is now uniformly lazy: eval always receives memoized thunks,
so short-circuiting needs no opt-in and each child evaluates at most
once (pinned in evaluate.test.ts "uniform laziness"). The lazy prop, the
invented dev/assertResults option surface, the NODE_ENV sniffing, and
the runtime output-assertion block are deleted — the compile-time
EvalReturn check is the check. eval's untypeable second parameter
(runtimeValues) is deleted; ident/path elements already deliver typed
values as bindings.
The correlated-bindings type machinery (13 aliases incl. a type-level
def-string splitter) is deleted wholesale. InferEvaluatedBindings is a
flat per-binding map; reference chains resolve transitively to the root
constraint's type via a tail-recursive ResolveReference. arktype match
stays the polymorphic idiom over the flat type, with .default("assert")
as the runtime guard (straddle pin kept in design-claims.test.ts).
EvalReturn now resolves resultType defs that EMBED binding references
("v | null", { value: "v" }) in a scope of the pattern's bindings,
mirroring the engines' per-parse scoped resolution — previously unknown.
DESIGN.md, V2-PLAN.md (D4/D5 reversal notes), and all docs snippets
updated in the same commit; docs build green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
…ike consts Answers the PR #6 review question "how are these different than just re-using ConstSchema?" — they aren't, once const matching is correct. BooleanSchema/NullSchema/UndefinedSchema, their factories, the three keyword node types, ParseKeywordPrimitive, and parseKeyword are deleted from both engines. Keyword literals are ordinary const-pattern nodes: { pattern: [constVal("null")], resultType: "null", eval: () => null }. The enabler is the word-boundary rule, implemented identically in both engines via parsebox's ident tokenizer: a const value that is one whole identifier matches only a whole identifier in the input, so `nullable` never matches constVal("null") and `andy` never matches constVal("and") (pinned in parser.test.ts, types.typetest.ts, design-claims.test.ts). Non-identifier values ("+", "==") match as raw text, unchanged. Also fixes a latent eraseRefinements bug this surfaced: the arktype JSON round-trip is lossy for unit types (the `undefined` keyword came back as the STRING literal "undefined"); erasure now round-trips only when a refinement was actually stripped. Unit keyword resultTypes are pinned working end-to-end (resultType "true" satisfies "boolean" slots). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
Answers the PR #6 review comment "safeParse.... throws?". An unresolvable schema def now returns { success: false, error: { code: "INVALID_SCHEMA", position: 0 } } instead of throwing — safeParse never throws, full stop. parse/evaluate/compile keep throwing for programmer errors, but now uniformly via StringentParseError carrying the same structured error (one error class, four codes) instead of an anonymous Error. Pinned in createParser.test.ts; DESIGN.md error model and the error-handling guide updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
The core of the PR #6 rework ("What is the purpose of the project if not to be type-safe?"). defineNode patterns are now authored through a fluent builder — pattern: (p) => p.operand("number | string").as("left") .constVal("+").operand("left").as("right").result("left").eval(...) — whose chained calls validate every arktype def against the bindings accumulated so far, via type.validate<def, $> in direct parameter positions (the scoped-validate twin of the D17 infer machinery): - operand("nmbr") is a compile error AT that call, with arktype's own message; rest("left") and rest("left | null") compile ("left" is a scope alias); refinement-on-reference, position-0/forward references, const-binding references, duplicate/reserved/type-shadowing binding names, and typo'd result defs all error at their exact call sites. - .result()/.eval() are chain methods, NOT config siblings: a pattern- dependent sibling property makes tuple inference order-sensitive (property order flips the result — demonstrated and pinned in design-claims.typetest.ts, alongside the validation pins). The chain sees the pattern's types locally and is order-robust by construction. - The builder is construction-and-validation only: NodeSchema still stores the same declarative pattern tuple both engines interpret — grammar computation and both parsers are untouched. - eval's return is checked against .result()'s def at the .eval() call; "resultType required unless passthrough" is now also structural (.eval only exists after .result). - Standalone element factories are gone from the public API (builder methods now); overlapping() remains as the symmetric-constraint marker. - Constraint-side createParser scope aliases become a runtime-only affordance (cast + construction check); call-site schemas keep full alias support. Cost: 1,083,879 → 1,136,550 whole-project instantiations (+4.9%) for complete definition-site validation; measured threshold noted in types.typetest.ts. Fixture, all suites, docs, playground, and README rewritten to the builder in the same commit; docs build green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
…peline
Kills the "scope aliases are runtime-only" caveat and its documented
as-never casts ("Not good at all" — PR #6 review). createParser now
carries TScope; the inferred scope (arktype's own scope.infer) threads
through Parser (safeParse/compile schemas validate via
type.validate<TSchema, $>), evaluate's values (type.infer<TSchema, $>),
Context, and the parse-level def algebra — so { created: "Timestamp" }
validates at the leaf, resolves in literal mode, and types the result,
cast-free (pinned in design-claims.typetest.ts and createParser.test.ts).
Two load-bearing perf rules, both canary-pinned in types.typetest.ts:
defs resolve UNSCOPED-FIRST (scoped inference engages only for
alias-referencing defs — paying arktype's deep generic path per
constraint check breaks the 30-term fold), and alias leaf defs resolve
ONCE at ident/path parse time into the existing "~resolved" carrier
(mirroring the runtime, where nodes carry their resolved Type). The
fold-accumulated result chain stays unscoped — threading it doubles
per-level forcing depth (measured); result defs cannot name parser
aliases anyway (builder-validated), leaving only a documented
conservative corner for template results over alias-typed operands.
Also pins a pre-existing, previously-uncanaried floor: identifier-led
left chains cap near 20 terms (literal-led: 30+) — true before this
change too. Whole-project instantiations 1,136,550 → 1,274,619
including the new canaries; threshold note updated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
Answers the PR #6 request for "a clear explanation of why assoc property was present, why lhs/rhs were added, demonstrate the issues with that design and why this change fixed it": the defining-a-grammar guide gains "Why there is no associativity property (history)" — the property could lie (the old runtime reinterpreted a left level's rhs() tail regardless of the declared value), lhs/rhs named position when they encoded parse LEVEL, and the shape-derived rule makes the pattern the single source of truth, with the 3-vs-7 demo pinned in design-claims.test.ts. The fixture links to it. Comment-claim sweep: every behavioral claim in source comments now traces to a pinned test, a design-claims entry, or a measured canary. HANDOFF.md (the pre-rework work plan) is retired; V2-PLAN's session handoff is marked CLOSED with a summary of what the rework changed. DESIGN.md remains the current contract. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
…anaries
An editor report (TS2589 on plain evaluate() calls, a spurious
"shadows a resolvable type" on .as("r")) exposed that the type-level
machinery sat too close to the instantiation-depth cliff on TypeScript
versions with less headroom than the 5.9 toolchain: 5.5-5.8 failed the
scoped canary in batch, and editor tsserver contexts (per-file, cold)
hit collapses even earlier.
Three fixes, verified against TS 5.5.4 / 5.7.2 / 5.8.3 / 5.9.3 / 6.0.3:
- The def algebra is now fully SCOPE-FREE: since alias leaf defs resolve
once at ident/path parse into the "~resolved" carrier, the scoped
string/object fallback in InferOfDef was dead code on every in-contract
path — removing it (and the $ params on DefAssignable/DefOverlaps/
CheckConstraint/ScopeOfBindings/ResolveSpec) makes constraint-check
instantiations identical for scoped and unscoped parsers: one shared
memoization set, ~41k fewer whole-project instantiations.
- ValidateBindingName FAILS OPEN on a collapsed validate: under a tight
budget arktype's type.validate can degrade to never, and
[never] extends [TName] is true — that surfaced as the spurious
"shadows a resolvable type" error on good names. Construction time
remains the authority for real shadowing.
- Canaries pin COLD floors measured across the version range (scoped
constant chain 25, alias-led chain 12) — a warm neighboring evaluation
was masking regressions that editors then hit first; comments document
the 5.9 capacities and the cross-version measurement procedure.
DESIGN.md's limits section now states the version dependence.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
…-tested: gone)
Prompted by the owner probing the pinned inference-poisoning limit with
a validate-carrying signature. That probe was the quartet's plain-input
variant (works, but surrenders input validation — "x+" compiles, typed
by its parsed prefix, throws at runtime — and its bare type.infer values
param SILENTLY unions the values argument into TSchema; both now
pinned). But it motivated re-testing the load-bearing half: is
validate + the deferred-conditional input still METASTABLE post-rework?
It is not. Re-tested across 8 declaration-order permutations (including
the original bisect's flip trigger) x TS 5.7.2/5.9.3/6.0.3, warm and
cold, plus a scoped-alias variant: exact inference everywhere. The
rework's depth reductions (scope-free def algebra, carrier resolution)
moved the shape off the instantiation edge.
So parse() and evaluate() now carry type.validate<TSchema, $> on their
schema parameter: a typo'd leaf like { x: "numbr" } is a compile error
at the leaf on EVERY entry point, in the parser's scope. evaluate's
values stay NoInfer-wrapped — the values-candidate poisoning is
unchanged and now pinned in both its loud and validate-masked silent
forms. design-claims.typetest.ts's quartet is rewritten around the
shipped shape (permutation canaries included); DESIGN.md, the guide,
and V2-PLAN gotcha carry the history note.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
… demo
- constVal is now an ordered ALTERNATION (first match wins): one
booleanLit node replaces the trueLit/falseLit pair everywhere —
p.constVal("true", "false").as("word").result("boolean")
.eval(({ word }) => word() === "true"). ConstSchema carries a values
tuple; both engines try members in order with the word-boundary rule
per member; ordering semantics pinned (longest-first when members
overlap) alongside the matched-text binding.
- StringentError is a discriminated union: PARSE_ERROR / TYPE_MISMATCH
carry required expected+found, UNEXPECTED_INPUT keeps expected
genuinely optional (the continuation hint), INVALID_SCHEMA is
position: 0 with neither. Variant interfaces exported;
StringentParseError (a class cannot be a union) exposes the structured
union on .error for narrowing. Error-handling guide shows the
narrow-on-code idiom.
- Pinned the arktype-generics alternative for correlated pairs
(type("<t extends string | number>", { l: "t", r: "t" }),
instantiated per member) next to the match idiom in
design-claims.test.ts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ
|
All three review comments addressed in e5f371d (couldn't reply on the threads directly — a pending review on this PR blocks review-comment replies from this account): booleanLit / const booleanLit = defineNode({
name: "bool",
precedence: 4,
pattern: (p) =>
p.constVal("true", "false").as("word")
.result("boolean")
.eval(({ word }) => word() === "true"),
});Word-boundary applies per member; first-match-wins ordering is pinned (list longer members first when they overlap, e.g. Discriminated error union — done. arktype generics — nice suggestion; verified on arktype 2.2 and pinned next to the match idiom in design-claims.test.ts: Full bar green: typecheck (incl. TS 5.7/6.0), 148 tests, build, package check, docs build. Generated by Claude Code |
Summary
Replaces the array-based pattern API with a fluent builder pattern that validates constraints, result types, and binding names at compile time where technically possible, and at construction time for plain-JS callers. This addresses the core design directive that typos in definitions (e.g.,
operand("numbr")) must fail where written, not silently produce dead grammar rules.Key Changes
Pattern Builder API: Patterns are now authored through a fluent builder (
PatternBuilder) returned bydefineNode'spatterncallback. Each element method (.number(),.string(),.operand(), etc.) appends an element and returns a builder whose last element can be named with.as(). Chain methods.result()and.eval()declare the node's result type and evaluation function.Compile-time validation: The builder validates every constraint and result type against accumulated bindings using arktype's
type.validate. Invalid defs error at the call site:operand("nmbr")is a compile error (typo in constraint)rest("left")compiles only ifleftis in scopeRemoved keyword literal factories:
boolean(),nullVal(),undefinedVal()are removed. Keyword literals are now ordinary const-pattern nodes:constVal("true").result("boolean").eval(() => true). This unifies the model — identifier-like const values match whole identifiers only (word-boundary rule), sonullablenever matchesconstVal("null").Binding scope as type parameter:
BindingScopetracks accumulated non-const bindings through the builder chain. Const bindings are excluded because they carry matched text, not a type, so constraints and result defs cannot reference them.Lazy evaluation model: Evaluation is uniformly lazy — every binding is a memoized thunk
(() => value). This enables short-circuit semantics (ternary, &&, ||) for every node without opt-in, and each child is evaluated at most once.Schema validation improvements:
safeParse()never throws; invalid schema leaves returnINVALID_SCHEMAerror codeparse(),evaluate(),compile()throwStringentParseErrorfor invalid schemas{ created: "Timestamp" }type correctly in literal mode with no castsExprSchema constraint type: Changed from
ConstraintSpectoConstraintSpec | undefinedto allow unconstrained expressions.Updated all fixtures and tests: Grammar definitions, test cases, and documentation examples now use the builder API. Design claims are pinned in
design-claims.typetest.tsanddesign-claims.test.ts.Notable Implementation Details
.result()and.eval()chain methods rather than config siblings — they see the pattern's types locally and are order-robust by construction.never(an unresolvable def), mirroring the runtime and binding-scope path.https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ