Skip to content

Fluent builder API for pattern definitions with compile-time validation - #7

Merged
eralmansouri merged 9 commits into
claude/v2-plan-review-e13a11from
claude/repo-onboarding-9o7s19
Jul 7, 2026
Merged

eralmansouri merged 9 commits into
claude/v2-plan-review-e13a11from
claude/repo-onboarding-9o7s19

Conversation

@eralmansouri

Copy link
Copy Markdown
Owner

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 by defineNode's pattern callback. 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 if left is in scope
    • Binding names are checked for duplicates, reserved names, and type shadowing
    • Forward references and position-0 references are rejected
  • Removed 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), so nullable never matches constVal("null").

  • Binding scope as type parameter: BindingScope tracks 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 return INVALID_SCHEMA error code
    • parse(), evaluate(), compile() throw StringentParseError for invalid schemas
    • Scope aliases now resolve at compile time AND runtime — schema leaves like { created: "Timestamp" } type correctly in literal mode with no casts
  • ExprSchema constraint type: Changed from ConstraintSpec to ConstraintSpec | undefined to 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.ts and design-claims.test.ts.

Notable Implementation Details

  • The builder is a construction-and-validation device only; what it produces is the same declarative pattern tuple both engines interpret (semantics stay data).
  • Tuple inference order-sensitivity is avoided by making .result() and .eval() chain methods rather than config siblings — they see the pattern's types locally and are order-robust by construction.
  • The unscoped def path is tried first; scope aliases engage only when it yields never (an unresolvable def), mirroring the runtime and binding-scope path.
  • Keyword-prefix guard (word-boundary rule) is now enforced uniformly for all identifier-like const values via the runtime's token matching.

https://claude.ai/code/session_01KVGCmuDTgVEC96mwK3WDKQ

claude added 9 commits July 7, 2026 11:19
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

Copy link
Copy Markdown
Owner Author

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 / true | false const — done, via a small feature: constVal is now an ordered alternation, so one node covers both keywords and the named const element binds the matched text:

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. constVal("==", "=")). Applied in the playground, fixture, docs, and the element reference.

Discriminated error union — done. StringentError is now a union discriminated on code: PARSE_ERROR/TYPE_MISMATCH carry required expected+found, UNEXPECTED_INPUT keeps expected genuinely optional (the continuation hint isn't always available), INVALID_SCHEMA is position: 0 with neither. Variant interfaces exported; StringentParseError (a class can't be a union) exposes the structured union on .error for narrowing.

arktype generics — nice suggestion; verified on arktype 2.2 and pinned next to the match idiom in design-claims.test.ts: type("<t extends string | number>", { l: "t", r: "t" }) instantiated per member states the correlation once and rejects mixed pairs — same backstop role as .default("assert"). Generic defs inside operand constraints could be a future direction if you want it designed.

Full bar green: typecheck (incl. TS 5.7/6.0), 148 tests, build, package check, docs build.


Generated by Claude Code

@eralmansouri
eralmansouri merged commit 04fd9ac into claude/v2-plan-review-e13a11 Jul 7, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants