Repository navigation
featherduster - #1685
featherduster#1685ssalbdivad wants to merge 4064 commits into
Conversation
060798f to
776daf2
Compare
|
@pullfrog review this |
There was a problem hiding this comment.
Important
Two reproducible crashes in the new copy-on-write helper copyOf (ark/schema/shared/transform.ts): it throws for every RegExp, and for any array carrying an own slice property. Both are reachable through the public API and contradict the "never writes to the input" contract this PR introduces. Details inline.
Reviewed changes
ArkErrorsno longer extendsArray— errors now live in a plainissuesarray with lazily builtbyPath/byAncestorPathcaches; iteration,length,summaryand Standard Schema support are preserved, and the new merge/countlogic tracks 2.2.7's traversal-stop semantics.- Copy-on-write
Transformreplacesclone— newcopyOf/mergeTransformedhelpers plusTransformErrorsinark/schema/shared/transform.ts; this is the source of both findings below. - New
arksetspackage — the set algebra is extracted from@ark/schemainto a separately installed engine (setEngine). Without it,@ark/schemaparses unreduced nodes and throwsmissingSetEngineMessageon relations/JSON Schema;arktypeimports it. I traced the extracted intersection loop (intersectConstraints) against its prior form and found no dropped-constraint or non-termination defect. - Public API/behavior updates —
configure()must now run before any package import;"+": "delete"removes undeclared symbol keys; root-morph failures throw from.assert; dates describe in UTC.
deepseek-v4.1-flash (free via Pullfrog for OSS) | 𝕏
| Error: () => new Error(), | ||
| Headers: (data: Headers) => new Headers(data), | ||
| Map: (data: Map<unknown, unknown>) => new Map(data), | ||
| RegExp: (data: RegExp) => new RegExp(data), |
There was a problem hiding this comment.
copyContentsOf.RegExp builds its copy with new RegExp(data), which always owns a non-configurable lastIndex. The descriptor overlay at lines 82-88 then redefines that property with configurable = true and throws TypeError: Cannot redefine property: lastIndex for every RegExp. This is reachable through the public API — e.g. type({ x: "string.trim" })(regexpWithOwnProp) (a RegExp with any own structure-transformed prop) routes through StructureNode.copy → copyOf.
Technical details
# copyOf throws on every RegExp
## Affected sites
- `ark/schema/shared/transform.ts:127` — `copyContentsOf.RegExp` produces a copy that already owns non-configurable `lastIndex` (and does not carry the source's `lastIndex`).
- `ark/schema/shared/transform.ts:82-88` — the overlay copies `Object.getOwnPropertyDescriptors(data)` (including `lastIndex`) onto the copy after forcing `configurable = true`; redefining the copy's non-configurable `lastIndex` throws.
## Evidence
`copyOf(/a/g)` throws `Cannot redefine property: lastIndex`; `type({ x: "string.trim" })` invoked on a RegExp with an own prop throws the same.
## Required outcome
Copying a RegExp must not throw and must preserve `lastIndex` plus any own enumerable props. Assigning `copy.lastIndex = data.lastIndex` (the property is writable) or otherwise avoiding the non-configurable descriptor collision would satisfy this. Typed arrays already short-circuit at line 80 for the same class of reason; RegExp needs equivalent handling.
## Open questions
- Are there other `copyContentsOf` kinds whose copy owns a non-configurable property the overlay would redefine? `lastIndex` appears unique to RegExp.| } | ||
| let copy: unknown[] | ||
| // slice builds its copy from data.constructor, which a named key can shadow | ||
| if (data.constructor === Array) copy = (data as unknown[]).slice() |
There was a problem hiding this comment.
This branch deliberately supports arrays with named keys (they are copied at lines 63-64), but it calls data.slice() through the instance, so an array that owns a slice property throws TypeError: data.slice is not a function. Reachable via e.g. type(["string.trim"])(arr) where arr.slice is set, since StructureNode.copy/SequenceNode call copyOf on the array.
The constructor shadowing is guarded on this very line; the call should use Array.prototype.slice.call(data) for the same reason.
| if (data.constructor === Array) copy = (data as unknown[]).slice() | |
| if (data.constructor === Array) copy = Array.prototype.slice.call(data) |
Two crashes in copyOf, both reported on #1685 and reproduced through the public API: - A RegExp's copy is `new RegExp(data)`, which already owns a non-configurable `lastIndex`. The descriptor overlay forced every descriptor to `configurable: true`, so redefining `lastIndex` threw "Cannot redefine property: lastIndex" for any RegExp with a transformed prop. A descriptor now stays non-configurable where the copy already owns that key non-configurably; `lastIndex` is writable, so the redefine succeeds and carries the input's value. - An array copied with `data.slice()` threw when the array owned a `slice` key. It now calls `Array.prototype.slice` directly, as the `constructor` guard beside it already anticipates a shadowing key. Both tests fail without the fix, jit and jitless. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… crash F9 escaped the fuzzers, none of which set "sideEffects": false, and the graph read had three barrels on one compiler. Each of 17 ways of reaching a validator through a side-effect-free module now runs under a stripped source, TypeScript to ESM and to CommonJS, and Rspack's swc to each, concatenating modules and not. A pruned build matching its whole one counted as sound, including where both crashed: the CommonJS barrels' ReferenceError passed on Rspack that way, and so did this harness's own `library` scenario, whose runner kept a type annotation and never ran. A crash they share now fails the run under its own count. A scenario filter takes a prefix, as these names are long.
… both 5bc7eb8 went in without its gate, and exactOptionalPropertyTypes refuses an explicit undefined for Scenario's only. pnpm lint and typecheckRepo exit 0 here.
F9 dropped a validator only under "sideEffects": false, which neither fuzzer ever wrote, so hundreds of their webpack apps said nothing about it. With ARK_FUZZ_SIDE_EFFECTS_FREE=1, an app's own package and its dependency declare it. It's a flag for a round rather than a drawn dimension, so the seeds in the notes still draw the same apps. Members seed 4500 with it, 60 apps on esbuild, Vite, prune:false, webpack, Rspack and the Node drivers: 0 unsound.
# Conflicts: # ark/aot/settingsValidators.ts
…n as built
`import { use } from "-!loader!./reader.ts"` runs only the loader it names, so
the plugin's own never reaches that module. The read took it as transformed
because of its file's name, and answered as it would for any other: a read of
`U.expression` in it is folded where the module is written, so U need not bake
it. Nothing could write the module, so the read stayed as it was and found
undefined on webpack and Rspack, on both default and smallest. A build keeping
every member throws there, as the same module is missed one at a time.
What decides is whether the module actually runs through the plugin's loader,
which each compiler says in its `loaders`, a persistent cache included. One that
doesn't is read as it was built, like what another plugin leaves: what it reads
is baked into the validators it reads, so the read gets the value arktype
returns rather than the throw of a whole build. This beats a refusal, since
nothing about the module is hidden from the read.
The same file built both ways is refused as being from two codes, even with
one text, or the first one read would decide for the other.
…oduction The options and dynamic-vs-precompiled pages still listed them among the builds reading one module at a time, which the as-built read ended for a production build. Where they don't prune, in development or under `prune: false`, they do read that way, so each page says that rather than dropping them. A probe of equal definitions across two modules, cycles and scopes included, compares the same on esbuild, webpack and Rspack in production.
…flag A blanket "sideEffects": false had every bundler drop `import "./config.ts"`, so all 12 configured apps of seed 61200 crashed on all 4 hosts, whole and pruned, with "types0.ts creates a Type before configure() runs". That's the program's mistake and the build saying so, and it hid what the flag is for in those apps, so they now list that module as having one, as a project would. Seed 61200 with it: 0 unsound on esbuild, Vite, webpack and Rspack.
# Conflicts: # ark/aot/settingsValidators.ts
What a program reads of its errors decides how much of the errors class ships:
`summary` alone, or `throw`, `toJSON`, `toString` and TraversalError too. The
analysis read `type.errors` and `ArkErrors` only where a module imported them
from arktype itself. A module re-exporting them, as a shared package's barrel
does (`export { ArkErrors, type } from "arktype"`), handed them to importers the
analysis never read, so a program printing or constructing the class through
one shipped neither tier and found `summary` undefined.
Each export a module re-exports from arktype is now followed through the
import graph to the bindings importing it, which are read as a direct import
is: so an `instanceof` test through a barrel still counts as a test, and any
other read ships the whole class. A namespace, a factory input or code outside
the bundle reading it isn't followed and ships it whole, as does `export *` or
`export * as` from arktype, whose names it can't tell apart from the module's
own. import(), require() and `import =` of arktype are refused already.
…a function expression functionsAsArrows and functionsDeclared each spelled out the same test for a function expression that's anonymous, sync and no generator; closedTextOf kept its own list of the keys holding types, which scope.ts already exports and whose extra keys only a class holds, which it refuses first. inGzipOrder wrote isFunctionExpression out, dropUnread guarded a Map lookup only identifiers key, and pluginName sat under BuiltRead's comment. Bundles are byte-identical.
… site of its own A size build's walker reads every key of every shape through one `data[k]` and one `k in data` site, so V8 looks each up generically, and a key that's absent costs about 600 instructions. ntwine's ThreadView declares 95 keys, 81 of them optional, and took 149K instructions per call under `smallest` against 6.3K before checkers wrote it (Zod 4 4.5 us, Zod 3 20 us, it 20 us). A shape of at least 48 optional keys now writes its Allows, and where it deletes undeclared keys its result, as text naming each key and calling the checkers it declares: ThreadView takes 8.0K instructions (1.6 us). Its Apply still walks, since a failing call's cost is in its issues, as does its transform where data isn't a plain object. The Allows text checks keys in arktype's order, stopping at the first that fails: a required key whose checker fails undefined is read without `in`, an optional key is checked only where `in` finds it, and keys holding the same check call one checker. The result copies each key in order, through its checker's transform, writing a literal default inline and holding a function's default's place until each transform has run, as failingDeletingProps does. ntwine `smallest`: 116.4 -> 118.8 KB gz, all of it ThreadView's one shape; no size row has such a shape. Rows pin deleting, defaults and transforms, rejecting, presence through inherited, non-enumerable and Proxy keys, a getter past a failure, and exactOptionalPropertyTypes: false, each against arktype. With every shape holding an optional key written this way, testPrograms 60:9103 passes, and the smallest differential's one disagreement is a checker root's transform the next commit fixes; ntwine's corpus answers as source does.
… reached two ways apart
type("unknown") and type.pipe() reach one keyword two ways, which arktype keeps
apart. A build reading each module alone named them alike until bf69dd9 read a
bound copy through the node it was bound from, so they now compare as arktype
does there too. The identity row pins it, and the equal-definitions section no
longer lists it among what such a build compares otherwise.
testCache binds every acyclic root's precompiled unit as the root finalizes, which is what it exists to check, so a Type has compiled code from its definition there. firstCall.test.ts's "no compiled code is built for a Type whose narrows read ctx until its second call" pins when the dynamic path compiles, which a bound unit replaces by design, so testCache excludes it by name as it does the jitless-only config tests. Its other cases, which compare what the first and a compiled call pass callbacks, still run under testCache.
…hecking a key at its path
A size build's root whose checkers hold a callback reading ctx applies through
its node, and wrote `node.allows(data) ? data`, as a checker root's transform
hangs off its Allows elsewhere: so `{ outer: { "+": "delete", v: narrowed },
other: "number" }` returned its input with the undeclared key still in it. It
now returns `node.tTransform(data)` wherever the root transforms.
Two more differences from arktype under the same root. A key whose value
transforms is checked before it's applied, and the walker checked it without the
key on ctx's path, so the callback saw ["v"] for ["outer", "v"]; a ctx-reading
checker now takes the key and checks at it, as compiled code pushes the key
first. And a check-only pass, as Allows-with-ctx and a pipe's check are, checked
such a value twice where it failed, where arktype, which only transforms what
Apply finds valid outside a check, applies it once.
Found by the smallest differential on firstCall.test.ts's "a key under one
deleting undeclared keys" (6 disagreements, every layout). The row pins the
result, each call's path and the call counts, plain and piped, against arktype;
it fails before this, and with the count fix keyed on Allows alone.
Bytes, smallest gz: moltar 1378 -> 1388, shop 3729 -> 3738, saas 5629 -> 5639,
login unchanged; the path's push lives in the ctx-reading checker, so only a
program holding one carries it.
…ther a transform's failures in one object allowingCtx, which checks a node reading ctx as Allows does, deleted the _at and failsUnion it had replaced, which turns a Traversal into a dictionary; every later read of that ctx was then a slow lookup. It restores the values it read instead. A transform that can fail allocated four closures and an object per call to hold what failed; one Written object now holds them. Instructions per call, ntwine `smallest`, alone in a fresh process, median of 3: ResolveInteractionInput/invalid 7014 -> 849, DispatchPreferences/dense 72.0K -> 56.3K, ThreadView/sparse 10.9K -> 10.7K, the rest within 10%. Round-robin over all 806 export rows, 9 interleaved runs: geomean 0.99 of before (halves 0.96, 1.02), rows over 3x the smallest before checkers wrote it 23 -> 14. The size rows are unchanged: login, moltar, shop and saas don't carry either.
…keys 48 optional keys reached only ntwine's ThreadView. Shapes of 8 to 47 optional keys still walked, and the walker's absent keys cost the same there: on ntwine under `smallest`, alone in a fresh process, instructions per call against the smallest before checkers wrote them: GithubRefCard/sparse 18572 -> 2812 (was 2668) Settings/sparse 10966 -> 2986 (was 1379) TranscriptMessage 37873 -> 7971 (was 7222) TranscriptPage/dense 48779 -> 11446 (was 5672) Below 8 the gain dries up against the bytes: round-robin over all 806 export rows, 9 interleaved runs, rows over 3x the earlier smallest go from 10-14 at 48 to 7-10 at 8 and 3-6 at 4, for 118.8 -> 123.2 -> 125.5 KB gz. What stays over 3x at any threshold is small shapes that transform, closed with a default (PrWatchView and the results holding it, DispatchPreferences): their cost is the walker's copy, not keys left absent. ntwine `smallest` 118.8 -> 123.2 KB gz; the size rows hold no such shape and are unchanged.
Brings in stage 256f7be: small-apps' errors read only as far as a program reads them, unions listing branches only where they read differently, narrows held in their cells, equal Types created apart where nothing compares them, and webpack and Rspack's production builds documented as reading the whole program. Resolved by hand: - checkers.ts keeps both the narrow written as a check and this lane's checkers, and a union takes stage's required issue with this lane's failing branches after it. - combinators.ts writes a nullable domain pair on stage's condition, no domain object and no branch transforming, which already rules out the failing branches this lane checked for, and passes a listed union's issue with them. - The issue features hold both lanes' fields: what checkers hold, and what a program reads of its errors. A hole's cell is the same only where it reads only data, returns reports alike and has the same text. - The equal-definitions bullet keeps stage's link to prune, names --emit and any build that doesn't prune as reading each module alone, and no longer lists the keyword reached two ways, which such a build now keeps apart as arktype does. The settings validators and the precompile llms page are regenerated.
…ports it
A standalone build resolves arktype to arktype/runtime, so a module re-exporting
a name the runtime lacks, as a shared barrel's `export { Type, scope } from
"arktype"` does, fails to link. R4 caught only an import read outside a site, so
the build failed at the bundler's link with no word of why or what to do.
Each value re-exported from arktype that arktype/runtime lacks is now R4 at its
specifier, whether or not anything imports it, as the re-export alone fails to
link. Its hint says to re-export only what the runtime has and import the rest
where a precompiled definition reads it. A cache build, running on arktype,
reports nothing, and `export *` passes, linking whatever the runtime exports.
…ewhere A program creating equal Types in two modules gets one value from arktype, which interns them, so `A.assert === B.assert` is true. A build creates them apart where no read can tell, deciding by the members the usage analysis saw: a call, or a member holding nothing of its own. assert is a Type's own, so read without calling it, as `A.assert === B.assert` or `[A.assert, B.assert]` does, two values were told apart and the comparison printed false. The analysis marks such a read piped, as it may be called with any arguments, so a program using piped now interns. traverse, from and toString, read the same way, already compared alike, being shared by every Type.
…ges leave it out 7951304 dropped " (was X)" from default messages by making en's default `actual` writer return "" for every code but `required`, and by converting a precompiled issue to an ArkError with `actual: ""`. That conflated two things: what `error.actual` is (a description of the data) and whether a default message prints it. A `problem`, `message` or locale writer that read `ctx.actual` got "" unless `actual` was configured, so `divisor: { problem: ctx => `${ctx.actual} ${ctx.expected}` }` wrote " % 2 !== 0" where its docs promise "3 % 2 !== 0", and a precompiled site's configured writer got "" too. Now `actual` always describes the data unless it's configured or passed to ctx.reject, and only the default text decides to leave it out: - The per-code en describers are restored from before 7951304 (domain, unit, proto, the lengths, notEqual, after/before, union, discriminant, predicate; printKind otherwise), and an undeclared key's value is described too. minLength's describer no longer returns "" for an empty value, which only existed to keep "(was 0)" out of a message that no longer prints it. - writeActual (errors.ts), used by writeText and the locale renderer, stamps an error whose actual came from one of en's describers (an identity set in errorWriters.ts, `describesData`). en's default problem writers read `printedActualOf(ctx)`, "" for a stamped error, so the default text is unchanged: no "(was X)" but "(was missing)". A configured or supplied actual isn't stamped, so it still writes "(was X)" in both modes, and `actual: ""` still hides it, error.actual included. A locale that inherits en's problem leaves the description out as en does; a locale's own problem (de's, or the integration test's) reads it. - The stamp is a private field installed on the error (as ErrorSource stamps #config), so an error stays a plain object to JSON, spread and for...in. A WeakSet was tried first: an entry per written error doubled an invalid call's cost (login and a nested union, read summary: 1.4us -> 2.8-3.8us). With the field, 4 interleaved rounds read fix 1496/1527/1710/ 1704 ns vs base 1453/1600/1763/1891 ns, within this machine's noise. The description is computed eagerly when an error is written (errors are written on first read already); a getter would cost a defineProperty per error and break the fixed shape compiled error builders give errors. - Precompiled: a written site (one with a configured writer function) ships the runtime's describer for its code only where a configured problem or message function can read it, else "" as before, and sets keeps bit 4 so writeIssue stamps the writer context and a default problem it computes leaves the description out. raisingTraversalOf's writers do the same. errorOfIssue no longer sets `actual: ""`, so an issue merged into a Type's errors describes its data; its text is kept in meta as before. - An atBases union with a configured meta.actual keeps `actual: ""`, as today: that is a configured actual, and forcing it keeps every locale's text as it was. Sizes (min/gzip, built, base 78c795b): every precompiled default bundle is byte-identical in length and identical in code modulo minifier identifier names (checked by normalizing short identifiers), so the gzip deltas are esbuild renaming noise: login 3132/1477 -> 3132/1480, first 1508 -> 1509, smallest 1275 -> 1269; moltar 1544 -> 1546, first 1569 -> 1569, smallest 1345 -> 1341; shop 5487 -> 5484, first 5503 -> 5504, smallest 3622 -> 3627; saas 10106 -> 10103, first 10129 -> 10133, smallest 5492 -> 5490. Login form b1 2152/1020 -> 2152/1019, b2 1962/987 same, b2 development 3954/1899 -> 3954/1900, optimizeErrors size 2116/1013 -> 2116/1012. Dynamic arktype bundles grow by the restored describers: +1424/+438 B (login), +1413/+494 (saas). Text is unchanged: testDifferential reports 0 disagreeing with ARK_PRECOMPILE_OPTIONS='{}' and '{"mutatesInput": true, "errors": "first"}'. Snapshots that pinned actual: "" now hold the description, the integration locale reads actual again ("<string>! (5)", reverting 9bf6816), and new tests pin a configured writer reading the description in both modes, an issue merged from a validator, an error's actual beside its message, and a locale's own problem against en's.
On the macOS runner a next build has hung twice on the release branch, at different steps, until the job's 45 minute limit, with nothing to show where. It doesn't reproduce on Linux (4 of 4 local runs pass in about three minutes). Each build now gets three minutes; a hung one prints what it wrote, runs once more, and fails with its output if it hangs again.
e4b54ea to
8599524
Compare
… it with claims The announcement, README and homepage buried the answer to the question a Zod user asks first: what does switching cost me, and what do I get. They now open with it. - README: the first screen is the scoreboard card, "Using Zod? Switch with one prompt" and an example with real 3.0 output, then a before/after, what carries over (names, messages, Standard Schema integrations), what changes, and a collapsed API table. It states no number in text; numbers stay in claims.ts and reach the README through the site's generated card. - Announcement: a TL;DR under the headline and a "Switching from Zod" section second, where "Migrating from Zod" was near the end. A custom message now shows as written everywhere, forms included, which is how a Zod message behaves and was the largest papercut a production migration hit. "The plugin can wait" says what an app gets before it precompiles. - Homepage: the hero's second button is "Migrate from Zod", the migrate section carries a custom message through its before/after and lists what you keep and what it costs, and five error outputs that still printed "(was ...)" match what 3.0 writes. - The social card printed "startup: 2nd of 23" under "Pick 3" while the board beside it said 1st: it read the raw index where the board applies the tie band (zod-compiler 1.0000, ArkType 1.0009). It now reads the board's place. New claims, each recomputed from the stored results and citable from prose: - dynamicAppSpeed / dynamicZodSpec: without the plugin, ArkType validated faster than Zod 4 on all 11 apps bundled with esbuild, by 1.65x on ntwine's packages/shared and 8.38x to 15.31x on the 10 generated, 9 of 9 paired runs each (sign test p 0.0039). Against z.compile, faster on 10 of 11 at p < 0.05 and tied on 1. - dynamicZodStartup: without the plugin ArkType ran 1.50x to 2.19x the instructions Zod 4 did from import through first validation, 9 of 9 on every app. Unflattering, and stated. - dynamicZodSize: without the plugin ArkType's bundle is 3.59x Zod 4's on valibot.dev's login form, 89,751 B against 25,058 B gzipped. Also stated. - zodStartup: precompiled, fewer instructions than Zod 4 on each of the 4 startup apps by 10.34x to 54.39x, 20 of 20 paired runs on Node 24. - zodSize: precompiled, 1,007 B gzipped on the login form against Zod 4's 25,058 B and Zod Mini's 5,127 B. - dynamicZodSpeed is pending and cited nowhere: the homepage benchmark's medians have the dynamic arm ahead of Zod 4 in 32 of 32 scenarios, but its paired verdicts were stored only for the precompiled arms. bench.ts reads an optional `arktypeVs` so the next release run can back it. appSpeed printed "p <= 0.039" for p = 0.0390625; p values now round up. Not changed, and for a decision: "smallest" holds only as a best average (second on each of the three independent size results, and it fails leave-one-out), and "quickest to start" holds in instructions, not wall clock. Also: READMEs for @ark/util and @ark/fs, and the extension's and @ark/aot's READMEs carry the current tagline and the skill command.
An error had two texts: `problem`, without its path, and `message`, with it.
A custom message could go in either, and the one people reach for, `message`,
was the one a form library never showed: a Standard Schema issue read
`problem`, so `.configure({ message })` and `ctx.reject({ message })` gave a
form ArkType's default text. Migrating a 171-file production monorepo to 3.0
took rewriting 143 such sites to `problem` before its forms said what they
had on 2.x. Zod has one message, and it shows as written everywhere.
There is now one slot. `message` never holds the error's own path, and
`problem` is gone from config, meta, `ctx.reject`, errors and locales. There
are two ways to say what's wrong, and they don't mix:
- Templated: configure `expected` (or `.describe()`), and ArkType writes
`must be ${expected}`, composes it into unions and intersections, and a
summary puts the path before it: `age must be an adult's age`.
- Custom: configure `message`, or pass one to `ctx.reject`, and that one
sentence shows verbatim on a direct call, in a Standard Schema issue and
under `flatMessagesByPath`. A summary sets it apart from its path:
`email: Enter a valid email`.
What follows from it:
- `summary`, `toString`, the thrown TraversalError and `toLocaleString` write
each error's line. A type no longer places its own path; a locale composes
the line through `Locale.line`, which en writes as above and de writes with
its subject and label.
- A Standard Schema issue IS the error, not a copy with another message.
- A union that lists its branches' errors still names each one's whole path
in a summary, and from its own path in its `message`.
- A union or intersection whose errors all share one custom message takes it.
- A pipe's configured `message` is its output's errors' too, as #1479 had it.
- A missing key shows its value's custom message, where it said
`must be a string (was missing)` whatever was configured: a message written
out for a value says what's wrong with it however it fails.
- A union's configured `expected` is templated like any other. It was written
bare, with no `must be` and no path.
- `flatProblemsByPath` is `flatMessagesByPath`.
- `problem` is a type error where it was accepted, and where a cast or
JavaScript passes it, `.configure()`, `configure()`, a scope's config and
`ctx.reject` throw `problem was removed in 3.0; write message`.
- Another library's Standard Schema issue embedded in a Type keeps its
message as written, as custom text; an ArkType Type's own, from this copy,
another copy or a precompiled validator, stays templated.
The lean issues `arktype/runtime` and precompiled validators write follow the
same rules, and the standalone compiler's sites carry whether a site's text
is custom. `ark/aot`'s half of this is in the next commit to that package.
Review of this change found, and this commit fixes: a union's message writer
ran a second time at an empty path; `summary` copied each error per line
(1145 ns for ten written errors, now 460 to 500; it was 65 before lines were
composed, and what remains is deciding custom-ness per line).
Riding along, from an audit of the release:
- perf(types): completing a string definition takes 15 to 21 ms on
TypeScript 6 and 3 to 6 ms on TypeScript 7's server, where this branch took
602 to 746 ms and 208 to 233 ms, and 2.1.22 took 89 to 154 ms and 39 to
68 ms. To complete a string argument TypeScript resolves the call with
inference from it blocked, by inferring the parameter's type to itself, and
wherever that met one alias on both sides it measured the alias's variance:
a structural comparison of everything validation reaches. `type("s")` spent
741 ms there. The parameters now go through `DefinitionArgument` and
`ValidatedArgs`, interfaces that declare `in out`, so nothing is measured,
with inference sites left in a dead branch so a lambda in a tuple
expression is still typed (declaring variance alone, or `NoInfer`, made it
`any`). One completion request instantiates 4,028 types, from 946,162.
`pnpm bench` totals +0.82%; a later call of a spread-argument form costs
+5% to +13%, its first far less. completions.test.ts bounds the request.
- An issue's hover is `ArkError<ArkErrorCode>`, not a 700-character union.
- fix: two lookbehind regex literals made `import "arktype"` a SyntaxError on
Safari before 16.4, which 2.x loaded on. testBuild fails on one.
- `console.log(out)` prints `ArkErrors { summary, issues }`, where it printed
a bare array though errors are no longer one.
- An unresolvable name suggests what to write: `'int' is unresolvable. Did
you mean 'number.integer'?`, for 54 names from Zod, TypeScript and JSON
Schema at both the type level and runtime (0 instantiations added), and for
typos at runtime.
- `configure()` rejects an option it lacks, in types and at runtime.
- A class as a definition is a type error and a ParseError saying what to
write. `type(Map)` threw `Constructor Map requires 'new'`.
- The German locale leaves the value out of its messages, as English does.
- The built `@ark/aot` resolved `arktype/internal/runtimeExports.ts` to the
full internal entry rather than the runtime's, so its checks of what the
runtime exports were wrong once packed, though right in every test, which
read source. `arktype` exports those three internal modules explicitly and
testBuild checks what each deep path resolves to.
- ci: the site no longer deploys when the publish fails.
- CHANGELOG: a summary of 3.0 at the top of Unreleased.
Deleted: `ark/repo/cyclicScaling.md`, an experiment that concluded in
d7f9e92 (`scope(cyclic100).export()` took 79.6 to 85.3 s on 2.2.8 and 210 s
on this branch before it, 406 to 702 ms after); the `publishExtension` script
for a package that no longer exists; `buildCjs`, `tsconfig.cjs.json` and
build.ts's `--cjs` branch, which nothing ran.
Known and not fixed here: `union.test.ts` "a discriminant doesn't skip a
predicate an earlier key tests" passes only after other files have run, on
this branch before this commit too.
`arktype-precompile --check` on a production Next 16 app (3,556 files, pages
router, webpack, workspace packages built to CommonJS) accepted 208 of 228
sites and reported 10 errors outside one. It now accepts 234 of 234 with no
change to the app's source, `next build --webpack` passes with only the
plugin and `transpilePackages` added to next.config.js, and what its forms
display is identical to the unprecompiled build on all 1,251 rows of a
harness that runs every exported schema.
What the build reads that it refused:
- A static helper's body may return from `if`s before its final `return`. A
narrow like `if (!exists(data)) return ctx.reject(...); return true` failed
every definition that passed it to a union with a unit branch, since
arktype calls a narrow on a unit while defining the Type.
- A narrow a union's unit calls and its other branches keep.
- What tsc writes for a CommonJS module: `exports.x = ...`, a
`defineProperty` getter, `__exportStar(require(...))` and `__importStar`.
A workspace package built to CommonJS was reported as
"<path> has no export <name>", which it had. A value read this way is
passed to the validator by its export's name.
- A helper holding a Type parameter is folded at each call, where the build
told its author to inline it.
- A call whose dynamic argument only a closure the call creates reads. This
precompiles a schema factory called per render with saved values its
narrows compare against.
- Composing a call's result, `helper().or(...)`, is a site.
- `typeof X.infer.a.b` types data, not a Type: an array typed from a Type's
`infer` was flagged for `.map`. Reading `.infer` or `.t` as a value, as
`withForm({ defaultValues: X.infer })` does for its type, isn't flagged.
- A tsconfig's `paths` apply to files under it that its `include` leaves out.
- An interface with a computed key threw while scanning, which silently
turned pruning off.
What it says where it still can't:
- One cause, one report. A Type chained from a definition that failed said
"X.array reads array, which a standalone validator lacks"; it now says
"X.array composes `X`, which can't be precompiled" and points at that
definition's own report.
- A value from a React hook says it's known only as a component renders,
where the build told the author to rewrite the hook as one expression.
- A definition that composes precompiled Types is no longer told to use a
`// @ark-runtime` island, which can't define it alone.
- The barrel warning names Next's `optimizePackageImports`, the packages and
the two ways out, where it said "built <path> from two codes".
- `--baked-limit` takes a number, as its option does; its usage said a path.
This commit also holds this package's half of the single error `message`
(1c12336): validators write `message` without a path and mark a site's
text custom, and the tests compare them against arktype's.
Measured on that app, total client JS against the unprecompiled 3.0 build:
+0.65% raw (+228 KiB), +0.41% gzip, with the options its config can safely
set; +2.94% raw with none. Pruning is what makes a precompiled bundle
smaller, and here it's off: `optimizePackageImports` builds a workspace
barrel once per set of names imported from it, and with the packages taken
out of that option the build refuses four sites whose enum a tsc-built module
loads with `require()`. The code of 234 validators costs about what the
parser did. `optimize: "size"` brings it to +0.11% raw and -0.23% brotli, not
adopted: it overflows the stack on cyclic data like
`type({ foo: { bar: "this" } })`, as it did before this commit.
Docs: a "Next.js with webpack in a monorepo" section in Setup, and
Troubleshooting entries for each message above.
…t following them broke
The guides were tested the way their readers use them: an agent holding only
the skill and its references migrated realistic modules from Zod 4, 3 and
Mini, Valibot, TypeBox, Yup, Joi, Effect and JSON Schema, with about twenty
integrations around them, and upgraded three ArkType 2.x modules holding only
the upgrade guide. Each result was type-checked and run against source, and
its output compared with the original library's. 43 rounds found 86 places
the migration guide was missing, wrong or made its reader guess, and 9 in the
upgrade guide. Each is fixed in the page that caused it.
- migrating.mdx is rebuilt around a nine-step workflow, the two config
options that match Zod's defaults, a table per library whose every row
type-checks, issue codes, and the semantics that differ: `.optional()` and
`.default()` against `undefined`, key stripping, unions under that config,
where a message must be written for an optional enum or a parse keyword to
say it, narrows that `.merge()` and `.pick()` drop, async pipes, and
definitions built at runtime.
- upgrading.mdx opens with a table of every breaking change and what to
write, and lists the adapters that still peer on `arktype@^2` and read
errors as an array (`@hono/arktype-validator`, `@hookform/resolvers` before
5, `sveltekit-superforms`, `@arkenv/core`, `@typeschema/arktype`), each with
the Standard Schema entry point that works today.
- SKILL.md gains the migration steps, a table of signatures for a function
that takes a Type, a decision table for error text (a Zod message is
`message`; `ctx.reject("x")` and `ctx.mustBe("x")` mean `must be x`;
`.describe()` or `expected` for text that composes), and a table from each
error an agent will hit to its fix, each gotcha stated once.
- errors, configuration, expressions, traversal, objects, scopes,
integrations (OpenAI and Anthropic SDKs), FAQ and packages pages: what the
dogfooding showed was missing from each.
Checked: 405 `ts` blocks type-check against source, 118 documented outputs
match what runs, and the docs build and `pnpm testSkill` pass.
Two pages broke the build through inline code holding a backtick: an escaped
backtick doesn't escape inside a code span, so the braces after it parsed as
an MDX expression. They use a double-backtick span.
testBuild expected a development build to log errors as a bare array, which
1c12336 changed to `ArkErrors { summary, issues }`.
Regenerated: the skill's migrating reference, llms.txt and llms-full.txt.
testBuild writes a barrel that re-exports `match` without using it, to check what the built Node driver keeps of it. It's a fixture the test leaves behind, like those under ark/aot/__tests__/temp, and failed `pnpm lint` on an unused import after any run of `pnpm testBuild`.
…Schema()
toJsonSchema() copies a node's meta into the schema it writes, so that an
annotation like `title` or `examples` survives. It skipped a function, which
JSON can't hold, but copied a string: `.configure({ message: "Enter an email" })`
wrote `"message": "Enter an email"` beside `"type": "string"`, and `expected`
and `actual` did the same.
Those three word arktype's own errors. No JSON Schema reader has a use for
them, a validator in strict mode rejects a keyword it doesn't know, and 3.0
makes `message` the slot people reach for first, so far more schemas would
have carried one than carried `problem` on 2.x.
Found while following the migration guide against Slash's forms, where every
field has a message.
271fb16 added six claims against Zod 4 (dynamicAppSpeed, dynamicZodSpec, dynamicZodStartup, dynamicZodSize, zodStartup, zodSize), a pending seventh, a rounding change to every printed p value, an `arktypeVs` reader in bench.ts and a change to the place the social card prints. The claims had already been honed to be accurate and compelling without overreaching, and none of that was asked for. claims.ts, bench/bench.ts and writeOgImages.ts are back to what they were before that commit, byte for byte. What cited the new claims goes with them: the announcement's "The plugin can wait" section and its two bullets under "The numbers", the homepage migrate section's "no plugin yet?" note and its "no build step" cost row, and the README's bundle-size bullet, which linked to the removed section. The announcement's existing "Without the plugin" line (dynamicSize) still discloses the dynamic bundle. Kept from 271fb16: the structure (switching from Zod first), the before/after examples and the five homepage outputs that printed "(was ...)", which 3.0 doesn't write.
…a stops at the alias depth
`optimize: "size"` writes a node as a call to a runtime checker unless it's
in a cycle, since a checker's Allows passes no alias depth on: the traversal
reading it drops the depth, and a compiled node below starts again from 0.
`isInCycle` decided that by comparing an alias's resolution with the node by
identity. `this` resolves to a node equal to the root it's written in, with
the same id, but not that object, so the root of `{ foo: { bar: "this" } }`
was judged outside its own cycle and written as `runtime.sited(...)`.
Checking data that is itself cyclic then never reached the 64-deep bound,
and the 1000-visit bound came after the stack ran out: a RangeError where
arktype returns "must be acyclic". The comparison is by id now.
It reproduces through `precompileStandalone`, so through the Node and Bun
drivers, `--emit` and the differential harness. The bundler plugin's own
path already compiled that root, which is why web-app2's builds with
`optimize: "size"` never hit it.
…ageImports
A production webpack or Rspack build reads the program it built to prune.
Next's `experimental.optimizePackageImports` builds a listed package's
entry as a module of its own for each set of names imported from it
(`__barrel_optimize__?names=a,b!=!<entry>`), each holding some of the
file's re-exports and nothing else. The read saw one file as several
modules of different code, gave up ("from two codes"), and the build fell
back to building each module on its own with every member kept, behind a
warning telling the app to take the package out of the list.
On Slash's web-app2, which lists 14 workspace packages there, that fallback
is what made a precompiled build larger than one shipping arktype: 831 units
of 557 KB against the 304 KB of arktype they replaced.
Such a module is now read as its file, whose text names every re-export:
- `builtEntriesOf` takes its source from the file rather than the module,
counts it as transformed without the plugin's loader having run on it,
and resolves each import it was built with by what the file names.
- an importer's request for it is read by the specifier its text names
(`named` on `BuiltImport`), and resolves under the request too, which is
what the module as the later loaders built it names.
- where the entry is no barrel, Next builds it as `export * from` the file
itself, an import of its own id, which is dropped.
- the loader records nothing for it, since nothing is written to it.
So the package stays in the list and the bundle is read whole. The warning
that named the list is gone with what it warned about.
…ollow may write
A pruned build refused a definition reading a holder whose module
something loads in a way the build doesn't follow: a `require()` or
`import()` of it, a dependency importing it, a namespace re-exporting it
("... so code the build doesn't follow may write it"). tsc's CommonJS
writes every import as `require()`, so every const object a workspace
package built to CommonJS shares between its modules counted, like each
enum of Slash's `@slashfi/models`: four of web-app2's sites were refused
by a pruned build that a build reading one module at a time accepted.
The refusal bought nothing. A site's factory checks each value it read as
it creates the validator, in every build, pruned or not: the
`checkInput(p0["limit"], 3, ...)` is in the pruned bundle too, and that
check is all a `prune: false` build ever relied on. So only a write the
build sees still refuses the site. A value written where the build can't
see is caught where it always was, as the validator is created:
"`H.limit` is 4, but was precompiled as 3".
`findElsewhere` no longer answers for a loose exporter or a module loaded
whole, `ProgramView` no longer carries which modules are loose, and the
hint for the refusal's message goes with it.
…roduction build A site's factory checks each value its definition read as it creates the validator. For an object or array read whole, like `type.enumerated(...Object.values(Plan.Enum))`, that was a `checkFacts` of its shape, naming every key, and a `checkInput` for each key with its value and label: 22 KB minified for one of web-app2's sites, reading an enum of 118 members, and 8 KB for another reading 182 currency codes. Together the creation checks were 46 KB of that bundle. Where a build checks no Types (`creationChecks: "none"`, a production build's default), a plain object or array of four or more primitives is now one `runtime.checkDigest(value, "<digest>", "`label`")`: a 53-bit digest over what kind it is and each own key, the type of its value and the value, with -0 apart from 0. The build computes it from the value it read, and the runtime from the value it's handed, so a key added, removed or changed fails as before, by a message naming the value rather than the key: "`currencies` holds other keys or values than it was precompiled with". A build that checks Types keeps each key's check and its message.
…y load a validator
A pruned build leaves out of its validators each member no read needs,
which it decides by following every read in the program. At the first
`import()` or `require()` of a computed specifier it gave up on the whole
program and kept every member, as such a call may load a module it never
followed. One icon loader, `import(`./icons/${name}`)`, did that to all of
web-app2's validators.
A bundler has no such doubt: webpack and Rspack build a module for each
file the specifier can name, and reach them through a module of their own
with no file, so `programAsBuilt` already marks each of them exposed, read
as code outside the bundle may read it. `ScannedProgram.exposesLoaded` says
so, and the scan then goes on past the call. Members are kept only where
one of the modules it may load exports a validator, by the same warning an
entry's export gets.
Members are still pruned for the program rather than per validator, so one
validator a computed specifier may load keeps `assert`, `meta`, `~standard`
and `methods` on every validator. A build that didn't come from a bundler
reads a computed specifier as before.
… SWC declare in CommonJS A validator stored at an object's key is followed to each read of that key by name, and to each read that may read any key, like `o[k]` or `Object.getOwnPropertyDescriptor(o, k)`, where the build loses track of it: it bakes each introspection member into it and keeps every member a production build would prune. A compiler emitting CommonJS declares helpers that copy one module's exports to another's, and each holds such a read. tsc declares `__createBinding` in every module with an `export *`, and SWC `_interop_require_wildcard` in every one with an `import * as`. A workspace package built by either is the program's own code, so one such module anywhere lost every validator stored at a key anywhere in the program, with a warning naming the helper: on web-app2, "because ../../be-libs/backend-env/lib/index.js:4:16 reads its descriptors", then "../../common-libs/slash-common/lib/services/__exports/index.js:165:48". Those helpers read a module's exports by key and nothing else, and what a module exports is followed by what each module imports. So no read in one is a read of a key a program stores a validator at, and the index of such reads skips their bodies: tsc's `__createBinding`, `__setModuleDefault`, `__importStar`, `__exportStar` and `__importDefault`, declared as tsc declares them (`var x = (this && this.x) || ...`), and in a CommonJS module the functions SWC and Babel name `_export`, `_export_star`, `_interop_require_default`, `_interop_require_wildcard`, `_interopRequireDefault`, `_interopRequireWildcard` and `_getRequireWildcardCache`. A function written by hand that reads descriptors by a key it's passed still loses it. This removes two causes, not the loss on web-app2: with both skipped, the same 82 of its 231 validators, each stored at a key of what a form library is passed, are lost at a descriptor read the app itself wrote, `Object.getOwnPropertyDescriptors(tvInstance)` in a design-system package. Following a stored validator to every read of any key can't hold track of one in a program of ten thousand modules, where some module always has such a read. The docs say so, and to set `members` there. Not recognized: tslib's copies of the helpers, which a package built with `importHelpers` imports, Babel's inlined `export *`, and esbuild's `__copyProps`.
…arge program whole
A production build that reads its program whole plans every module, then
follows each validator through it, twice: once for the members to prune and
once for those to bake. Each step resolves the same imports again and
again, as a guard's test or a binding's value is read for each validator
reaching it, and `createNodeHost`'s resolve ran the resolver and a
`realpath` for every call.
On web-app2's client program (10,408 modules, 231 validators), with
nothing else running:
before after
planProgram 153.9 s 17.2 s
usedIn 102.1 s 75.7 s
readingsIn 100.3 s 73.6 s
A profile of the three had 41% of its time in `realpath` and 48% under the
host's resolve. Next runs a scan in each of its compilers, which is where a
build reading this app whole went from 3 to 5 minutes to 22 to 28.
The host now keeps each answer by importer and specifier. That makes
nothing staler than it was: the resolver already keeps what it found of a
file, there or not, for as long as it lives. A file created after a miss
stays unresolved, and one removed after a hit stays resolved, with or
without this.
What's left is the following itself: each validator stored at a key is
sent to every read of any key in the program, so `usedIn` and `readingsIn`
are each about 75 s here.
…igh arktype
The default build compiles each validator to the code that checks its Type
fastest, and that code grows with every Type, where arktype doesn't. Past
some number of Types a precompiled bundle is larger than one that ships
arktype and creates them as it runs, and nothing said so.
That is web-app2 with everything else working. Read whole, pruned, 231
validators: 394 KB of units (one copy of each, 446 KB as its chunks place
them) and 23 KB of runtime against the 304 KB of arktype they replace, the
bundle 103.5 KiB larger than on arktype. With `preset: "smallest"` the same
build is 65.3 KiB smaller than on arktype.
So a production build reading its program whole, with `optimize` unset,
sizes what it wrote against arktype and warns where that's larger, naming
both ways out: `preset: "smallest"`, or `optimize: "speed"` to keep the
validators compiled and say no more.
The size is an estimate (`validatorsToArktypeOf`): what the sites reach of
the modules written and of the runtime, over what `type` reaches of
arktype, each declaration's length with names shortened and strings kept
(`minifiedLengthKeepingStrings`). `minifiedLengthOf`, which shortens the
words in a string too, read web-app2's validators, a message on each
field, as 0.95 of arktype when they are 1.37. arktype's own source
shortens further than written code, whose names are short already, by a
factor measured on real bundles:
program estimate measured
400 number ranges 0.27 0.26
576 0.38 0.38
900 0.58 0.57
1600 1.02 0.99
web-app2, default build 1.24 1.37
(esbuild bundles for the ranges, Next's webpack build for web-app2.)
Sizing a flat bundle also found a declaration that destructures, `const
[a, b, ...] = (() => { ... })()`, counted once for each name it declares:
it's counted once.
A build reading one module at a time has no bundle to size, so it doesn't
warn.
…dator For the changes since 4289102, which wrote this setup as one that builds each module on its own: - Setup, Next.js with webpack in a monorepo: a package stays in `optimizePackageImports`; a const object a package built to CommonJS shares between its modules is precompiled, its validator checking the value as it's created; a computed `import()` doesn't stop pruning. Leave `prune` unset, and build with `preset: "smallest"` where size matters. - Options: a production build checks a list or enum read whole by a digest; what `prune` reads of Next's barrel modules and of a computed specifier; the warning where compiled validators outweigh arktype, under "Choosing smallest"; and under `members`, that the helpers tsc and SWC declare in CommonJS aren't followed, but any other read of a key the code doesn't name loses each validator stored at one, so a large app sets `members`. - Troubleshooting: the refusal for a value "code the build doesn't follow may write" is replaced by the mismatch a validator throws as it's created; Next's barrel entry folds into "from two codes"; the new warning has an entry. - The changelog's paragraphs on webpack builds, size builds and baked members say the same, and llms.txt is rebuilt from the pages.
…ck of it A validator the build loses track of keeps every member whatever else reads it: `reading()` bakes each introspection member and keeps each pruned one as soon as `lost` holds one entry, and only the first entry is ever reported. `Follow` went on regardless, and a validator stored at a key is sent to every read of any key in the program, so each lost one still walked every such read and all that flows from it. Now nothing is pushed or read once a validator is lost, and the loop sending it to each read of any key stops there too. A loss past a dependency's read (`quietlyLost`) doesn't stop it, as a later loss in the program's own code is the one a warning names. On web-app2's client program (10,408 modules, 231 validators, 97 of them lost: 82 stored at a key of what TanStack Form is passed), scanned alone: usedIn 75.7 s -> 6.3 s readingsIn 73.6 s -> 4.7 s with the same 97 lost and the same first reason for each. `next build --webpack` of that app compiled in 16.3 min before and 4.7 min with this and the two changes after it, which weren't timed apart in a build. No test: nothing observable changes but time. The suite's readings are unchanged.
…what it checks, saying it
A size build writes each node it can as a call to a runtime checker, and
compiles the rest. A checker reports a code and a description, so a node
whose site says a configured message had to be compiled, and with it every
root above: a required key whose missing site says its value's message kept
its whole object compiled.
That is how an app writes a form. web-app2's fields are
`type("string > 0").configure({ message: "Name is required." })`, one
message a field, so under `preset: "smallest"` only 127 of its 200 site
roots were checkers, 179 of 621 written modules still declared a compiled
traversal (317 KB of 702 KB of source), and each field was a unit of its
own with two or three sites holding the same sentence.
Now:
- A root no structure hangs off, each of whose references says the message
configured for it (`.configure()` reaches them all), is
`saying(<checker>, message)`: the checker of the same root without the
message, written in place, and its message once. `saying` passes its
checker a ctx whose `_at` adds the message to each site, restored when it
returns, so `string > 0` is the one checker every such field shares and
only the sentence is the field's.
- A key's checker holds the message its missing key says, so `props`
reports it: a field's own where it is `saying`, else
`sayingMissing(checker, message)`. A required key with a message of its
own no longer compiles its object.
- A basis or refinement saying a message under any other root, like an
array with a minimum length, an object, or a number narrowed after it was
configured, is `saying(<check>, message)`, as a check is its own site.
The shapes (`stringRange`, `arrayOf`, the object basis `props` checks)
are left to roots without one.
A message a function writes, one configured for a code rather than a Type,
a union listing its branches' issues and a narrow or morph reading its ctx
are compiled as before. A unit saying a message sets the build's
`writesText`, as a compiled site's did by its ref.
On web-app2's client program, what its sites import bundled and minified
with the runtime (esbuild), `preset: "smallest"`:
validators 184,389 -> 103,656 B
runtime 22,371 -> 22,956 B
together 206,760 -> 126,612 B raw, 46,914 -> 34,231 B gzip
181 of 200 site roots are checkers after the first step, and 14 of 517
modules still declare a compiled traversal (29 KB of 473 KB of source):
four forms holding a morph whose callback reads its ctx.
Tests: checkers.test.ts, "a message configured for a Type": each issue's
code, expected and message and the summary as arktype prints them, for a
field missing, invalid and valid, under a union, and for an array, an
object and a narrowed number, in the default build and the size build, and
what the size build wrote. Slash's parity harness shows the same text as
arktype on all 1,251 rows with these checkers.
…mpiled, would outweigh arktype An unconfigured production build compiled every validator for speed and, since e3e2a02, warned where that came to more than the arktype it replaced. The warning named the fix and left the bundle larger than one not precompiled at all: web-app2's 231 validators were 416 KB with their runtime against arktype's 304 KB, so the default made the app 103.5 KiB larger. A default that makes a bundle larger is the bug, not the missing setting. Now the precompiler reports the estimate (`timesArktype`, where `optimize` is unset and it exceeds 1) and the bundler plugin acts on it by what loads the bundle: - a browser (esbuild's `platform`, a webpack or Rspack compiler's `target`, Bun's `target`, a Vite client build): the worker restarts with `optimize: "size"` and reads the bundle again, and the build warns that it did, naming the settings that build so without the second read. `optimizeErrors` stays `"speed"` unless set, so the full error runtime ships and a runtime island still works, and `lazy` is left alone, since when a Type is created is the program's to decide: `preset: "smallest"` is smaller still (5.8 KB on web-app2). - a server (target node): left compiled, silently. Nothing downloads it. - unknown (Rollup, Rolldown, a Vite build of several environments, and Turbopack, whose one read holds the server's modules with the browser's): the warning as before. An explicit `optimize: "speed"` or `"size"` is never estimated, so it is honoured without a word. The estimate also stopped counting a flat bundle's replaced unit modules, which the written program still lists: an esbuild bundle of 48 ranges read 3.4 times arktype in the plugin and 1.5 through the precompiler. In `next build --webpack` of web-app2 with no `preset` or `optimize`, the client compiler printed "…would be about 1.2 times the size of arktype…so the build wrote them as calls to checkers they share" and the server compiler nothing about size. With the message checkers of the commit before, by source map over every client chunk: validators, one copy 393,603 -> 145,098 B (178,861 as placed) runtime 22,764 -> 26,912 B together 416,367 -> 172,010 B arktype: 303,611 whole client JS vs the app on arktype: +103.5 KiB -> -149.1 KiB raw, +17.4 -> -33.6 KiB gzip Slash's parity harness shows the same text as arktype on all 1,251 rows with the options this chooses. Tests, prune.test.ts "validators larger than arktype": the estimate for 48 ranges, none under `smallest` or `optimize: "speed"`; an esbuild browser bundle identical to one built `optimize: "size"`, with the warning; a node bundle left compiled, silently; webpack and Rspack by `target`.
…, in a size build
A factory declares a node its own traversals read before them, as an empty
object, and fills it once they exist. Each wrote the fill out whole:
runtime.freeze(runtime.assign(shape0, {
allowsCtx: true, checksCtx: true,
tAllows: traversals4[0], tApply: traversals4[1],
allows: data => runtime.allowsUntracked(shape0, data) ??
runtime.allowsInContext(shape0, data, runtime.runtimeConfig),
$: runtime.runtimeScope
}))
`runtime.ctxNode` already builds exactly that node for a unit declared at
module level, so the members and the function answering `allows` were in
the bundle once for those and once more in every factory. It now takes the
declared object as a fifth argument and fills it, and a size build that
details errors writes
runtime.ctxNode({ checksCtx: true }, traversals4[0], traversals4[1], void 0, shape0)
A build for speed, and one whose errors don't detail, write the fill as
before: the first inlines what it can, and the second's `tApply` isn't a
traversal `ctxNode` is passed.
web-app2 has 33 such shapes (forms built by a helper that holds a narrow or
pipe reading its ctx). Offline, client program, `preset: "smallest"` with
`members.expression: false`: validators 76,538 -> 74,579 B, runtime
22,877 -> 22,900 B; 99,415 -> 97,479 B together (-1,936), gzip
29,485 -> 28,976 (-509).
Test, checkers.test.ts "has the runtime fill a node its own traversals
read, where a callback reads its ctx": a root narrowed by a callback
reading its ctx, above a helper's narrow that reads its own, prints
arktype's issues compiled and as checkers, through the root, `allows` and
an array of it; the two `ctxNode(…, shape0)` calls are exact and no shape
writes `allowsUntracked` itself.
… its imports through a Set Profiling the scan of web-app2's client program (10,408 modules, 128 of them writing validators) after 8bd9e3e: 37.7 s, of which 13.7 s was `isOnCycle` and 3.5 s the dependency list of each module written. `isOnCycle(module)` reads every module the module's text imports reach, from disk, to see whether one imports it back. `isBindingSetBefore` asks it for each input of each site, so a module read everything it reaches again for every imported helper its definitions call: a quarter of the whole scan was `readFileSync` (9.7 s). The answer is now kept by the module's id and source, and dropped with the import components (`componentsById`, the same graph) when `forget` hears a file changed. `textClosureOf` and `ModuleGraph.dependenciesOf` collected what they reached in an array and asked `includes` of it before each push, quadratic in a closure that is thousands of modules for an app read whole. Both collect in a Set, which iterates what is added as it goes in the order added, so the lists come out as before. Same program, nothing else running: 37.7 -> 24.9 s with the first change, -> 19.2 s with both. What it writes is identical, module for module (446 written modules compared as JSON). What is left is spread: planning (the kind solver under `analysisOf`) 9.1 s, following validators 5.8 s, and no function above 2 s of its own. Test, drivers.test.ts "answers anew once another module's change closes an import cycle through it": a watch build's worker answers for an unchanged main.ts before and after app.ts comes to import it; the second answer refuses the input that cycle could run early and equals a fresh worker's. It fails with the kept answer not dropped in `forget`.
`pnpm buildDocs` writes the precompile docs' llms.txt from the pages. It now holds what 37efdf8 and 9cc2140 added to options.mdx and troubleshooting.mdx: a Type configured with a message written as a checker saying it, a browser's bundle written for size where its validators compiled would outweigh arktype, and the two messages that choice prints.
A helper the build folds at each call could hold only consts, `if`s that
return and a final `return`. Checking what the Type it builds infers is a
statement of its own:
const editSchema = (saved: Address) => {
const schema = address.narrow(a => same(a, saved) || valid(a))
schema.infer satisfies entity.IAddressModel
return schema
}
so the build refused every call: "editSchema is not a static helper: it runs
`schema.infer satisfies entity.IAddressModel`". The only way to keep the
check and the precompiled calls was to state it outside the function, on
`ReturnType<typeof editSchema>["infer"]` through a cast of `null`.
The statement does nothing as it runs. `infer`, `inferIn`, `inferOut`,
`inferIntrospectableOut` and `t` exist only as types, undefined on a Type and
on a validator alike, and `satisfies` is erased. `statementsOf` now leaves out
an expression statement that is one of those members read off an identifier
under `satisfies`, as it leaves out a directive, so it may stand anywhere in
the body. Anything else under `satisfies` still runs and still keeps the
helper from being static: the test's second helper reads `.expression`.
Found in Slash's web-app2, whose two per-call schema helpers check their
result against an API type. `satisfies Type<X>` on the returned expression
is what they had before, which makes TypeScript compare two whole Type
instances.
Parsing "'foo'[]" alone costs ~817 instantiations; with a passing satisfies Type<string[]> it is 851, so the check itself costs ~34. The existing assignability tests' ~249k comes from their failing cases.
…yTypes
const Age = type("number | undefined")
type("unknown").pipe(Age).infer // number, where it is number | undefined
`inferMorph` reads what a Type piped to infers by `morph extends
type.cast<infer tMorph>`. `type.cast` declares its `[inferred]` key optional,
and a Type declares it required. Without exactOptionalPropertyTypes an
optional key's type already includes undefined, so TypeScript matches the
Type's undefined against that one and infers the rest.
1bf17e9 fixed the same read in `inferDefinition`, for a Type used as an
object's value or a tuple's element; this is the other place the published
declarations match a cast. `inferMorph` now reads the required key first and
falls through to the cast for a value that only has the optional one.
tsCompat's index.ts is checked against the built packages with the option on
and off (`pnpm testTsCompat`). It now asserts the pipe, `.to()` with a Type,
and that a plain `type.cast` value infers as it did, a
`type.cast<string | undefined>` among them. Before the fix the pipe assertion
failed under tsconfig.loose.json alone.
`pnpm typecheckRepo`, the typed pipe, type and declare tests and `pnpm bench`
pass with no baseline moved.
Reported from Slash, whose mobile app builds without the option.

Based on 2.2.7 (1ee4923): 565 commits, 189 files. A draft for review by area; the history gets rewritten into reviewable ranges after review.
Suggested reading order (each a
git diff 1ee4923b..featherduster -- <paths>):ark/util,ark/regexarksetspackage:ark/sets,ark/schema/shared/{intersections,sets}.ts(git diff 3166b30ab featherduster -- ark/setsshows what changed after the verbatim move)@ark/schemacore and perf, excluding cycles and Transformclone:ark/schema/shared/transform.tsark/type(public API, lazy keywords,ArkErrorsno longer extends Array, CHANGELOG)ark/repo/{bundle,build,testBuild,publish}.ts, per-packageinternal.tsark/schema/roots/alias.ts,ark/schema/generic.ts,ark/schema/shared/utils.ts,ark/type/__tests__/cyclic*(a rewrite follows as its own PR)ark/docsKnown before review:
allowsthrows a RangeError on valid rings from 38 members (12 jitless).Issues this closes
Each was verified against this branch by a test or probe.
Closes #1121
Closes #1473
Closes #1306
Closes #1470
Closes #1529
Closes #1555
Closes #1548
Closes #1530
Closes #1577
Closes #1430
Closes #1600
Closes #1676
Closes #1445
Closes #1160
Closes #1023
Closes #579
Closes #928
Closes #930
Closes #944
Closes #1026
Closes #1630
Closes #1237
Closes #1082
Closes #1476
Closes #1486
Closes #1587
Closes #1437
Closes #1457
Closes #961
Closes #1380
Closes #1543
Closes #1568
Closes #1598
Closes #1370
Closes #1403
Closes #909
Closes #1485
Closes #810
Closes #1498
Closes #1243
Closes #1273
Closes #1481
Closes #1412
Closes #1532
Closes #1490
Closes #1390
Closes #1575
Closes #1492
Closes #1479
Closes #1337
Closes #1310
Closes #1663
Closes #1525
Closes #1448
Closes #1435
Closes #1491
Closes #1287
Closes #963
Closes #1524
Closes #1571
Closes #1475
Closes #1554
Closes #925
Closes #751
Closes #1707
Closes #1720
Closes #1719
Closes #1724
Closes #1469
Refs #1462
Thanks to @RaphaelFakhri (#1721), @louisss1016 (#1722), @RClaudiuM (#1725), @SynthLuvr (#1715), @lprnmns (#1705) and @ybai08 (#1695), whose PRs these fixes started from.