types/rtti: read a tuple schema by length, not by enumerable entries - #1712

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

We plan to add optional types at the end of tuples. For example, const a = [number, bigint, option(string), option(boolean)] means type A = readonly[number, bigint, string?, boolean?]. How can these changes affect the plan?

Short answer: it doesn't affect that plan, and it removes an obstacle to it.

Your example is untouched. This PR only changes how a sparse schema is enumerated; on a dense array Array.from(rtti, …) and Object.entries(rtti) produce the same list. I ran const a = [number, bigint, option(string), option(boolean)] against both 6228f0e (base) and ab2cab7 (this PR's head), through all three readers:

Identical, and close(a) likewise. The mechanism your plan builds on — getItem reads past the end as undefined, and a member is required exactly when its set excludes undefined — is not touched here, so [1, 2n] is already accepted today.

Where it helps: arity becomes well-defined. readonly[number, bigint, string?, boolean?] is a claim about how many positions a tuple schema has and how many of them are optional. After this PR declared.length === rtti.length always. Before it, Object.entries could under-count, and close's fits check used that under-count — so a full-length value was rejected:

const s = close([number, , string])   // three positions
validate(s)([1, undefined, 'x'])
// base:    error  (declared.length was 2, so fits required length <= 2)
// this PR: ok     (agreeing with the data form, which said ok all along)

An optional-suffix rule stated over declared.length would have inherited that.

The type level already reads by length, which is the part I'd most want settled before the plan lands. TypeScript types [, number] as const as readonly [undefined, typeof number], so Ts<> has always treated a hole as a declared undefined position — verified with Assert<Equal<Ts<typeof sparse>, readonly [undefined, number]>>. Before this PR the runtime agreed with neither Ts<> nor the data form; now all three read a tuple schema the same way. When TupleTs grows the X? rendering it will map over keyof T, which is length-based — so the runtime it has to agree with is the one this PR installs, not the one it replaces.

One thing to decide when the plan lands, not now: a hole is the degenerate optional — its set is exactly {undefined}. So [number, ,] renders as readonly [number, undefined] today and would presumably become readonly [number, undefined?] under the same rule that turns a trailing option(string) into string?. Worth one row in validate/proof.f.mjs's acceptance table at that point; nothing to change here.

Generated by Claude Code

Thanks — both taken, in f3dfaef.

The unnamed acceptance change. Confirmed exactly as you wrote it, and it is sharper than "declared but unsatisfiable": a tuple's getItem is value[Number(k)], so Number('foo') is NaN and the declared foo was matched against the property literally named NaN. On 6228f0e:

const s = Object.assign([number], { foo: string })
validate(s)(Object.assign([1], { foo: 'x' }))  // error — foo was never read
validate(s)(Object.assign([1], { NaN: 'x' }))  // ok

So the base behaviour was not just stricter than the data form, it was checking the wrong property. It now has all three of the things you said one of would do: a second changelog line, a README paragraph under "A hole is a declared position", two acceptance-table rows ([1], and a value that actually carries foo), and a proof. tupleSchemaEntries' doc comment names it too, since that is where the rule lives.

The verdicts. Added sparseTuple to validate/proof.f.mjs, stating outright what the agreement tables only imply — assertError(validate([, number])([9, 5])) included, plus the closed arity (declared.length is the schema's length, not its key count) and the non-index property. I re-ran your mutation on the one that matters most, tupleSchemaEntries back to Object.entries: all three new groups fail, so they are load-bearing rather than restating the table.

npx tsc clean, fjs t 3383 → 3386, fjs/types/rtti/**/module.f.mjs still 100% line/branch/function.

Generated by Claude Code

All four corrections taken; three were in the body, one in 07eccbb.

The stale Changelog: section. Right, and it had been stale for three pushes. The body's section now mirrors changelog/unreleased/1712.md item for item — both **BREAKING CHANGES:** lines, same wording. I also added a short paragraph to the "disagreement" section for the non-index change, which the body described nowhere: it was carrying the hole story alone while the entry file carried two.

The riders. Both confirmed rather than taken on trust — git diff 6228f0e..HEAD -- validate/proof.f.mjs shows ten added rows entries (five open sparse, three closed sparse, two non-index), so "eight" was wrong from f3dfaef onward; fjs t is 3386. Fixed.

The todo nit. Correct, and the fix is 07eccbb. I dated the split to a6117ea's parent, which is wrong twice over — that commit is doc-only, and so is its parent's predecessor. I re-ran both probes at 4eb0142, this PR's code commit: iterator [1] and inherited [undefined] are already error/error there. The todo now names 4eb0142 and says every commit from it onward agrees, instead of pointing at a documentation commit.

Thanks for the mutation attribution on sameAcceptanceAsParse vs sameAcceptanceInTheDataForm — that validate and parse share the reader, so only the data-form comparison can catch a non-index regression, is exactly why those two rows are in the table and not just in the sparseTuple group. Worth having stated.

npx tsc clean; 07eccbb touches one todo/ file, so Changelog: none on that commit.

Generated by Claude Code