Repository navigation
Generated TypeScript: name the entry points, mark the plumbing internal, define shared constants once - #172
Merged
Merged
Conversation
added 2 commits
November 15, 2026 07:00
The schema digests, the package's connection digest, the Hello, the protocols' numbers and the calls' numbers and names, read from the blessed fixtures and compared with a record taken from the generator as it stands. A change to how generated code is laid out has to leave all of it as it is.
…al, define shared constants once (#170) - A header on connection.ts and, in lib mode, on the root index: what to implement, serve, dial and call for the package's shape, lockstep protocols included. - /** @internal */ on the wire plumbing: params layouts, call tables, HELLO, handshake(), provideServices / provideClientServices, and dispatchers the package's Services builds. Params interfaces and type layouts are not marked: the user-implemented interface and other packages name them, and a consumer's stripInternal would leave their declarations dangling. typecheck:stripped type-checks the stripped declarations. - Format and CONNECTION_IR_HASH are defined once, in wire.ts, when more than one file would define them; connection.ts re-exports them. Not in connection.ts itself: it imports every protocol file, so they would import it back. A lone file keeps its own. - connect()'s doc no longer says it provides services when it takes none. No wire change: wire-invariance.json is unchanged but for the keys of the three fixtures that moved into directories, and for link_jsonrpc/'s newly blessed wire.ts naming the package's declared codec.
Kinflou
marked this pull request as ready for review
November 14, 2026 23:34
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #170.
Generated TypeScript now says where to start, marks the wire plumbing
@internal, and definesFormat/CONNECTION_IR_HASHonce. No wire byte, number or hash changes.What changes in the output
Entry points.
connection.tsand, in lib mode, the rootsrc/index.ts(with@packageDocumentation) open with a header naming what to implement, serve, dial and call for the package's shape:The root index names the same through the barrel's namespaces (
chat.admin.Admin) and adds a line per lockstep protocol:`chat.Chat` has its own framing: implement it and run `chat.serveChat(impl, transport)` (which serves `chat.ChatDispatcher`), or dial with `await chat.ChatClient.connect(transport)` and call `client.send(…)`.A package with no protocol gets no header. A code-mode lockstep file has no package entry, so it gets none./** @internal */on*ParamsLayout,*_CALLS,HELLO,handshake(),provideServices/provideClientServices, and a<P>Dispatcherthe package'sServices/ClientServicesbuilds. A lockstep dispatcher (nothing covers it) stays public.FormatandCONNECTION_IR_HASHlive in a newwire.tswhen more than one file would define them (every protocol file that needs one, plusconnection.ts). Protocol files drop their copies and importFormatonly where a lockstep helper uses it;connection.tsimports and re-exports both, soconnection.Formatstill works. A package with a single defining file keeps its own, sochat.tsis unchanged apart from the markers. A schema namedwireis refused, as one namedconnectionis.Doc fix.
connect's comment no longer says it providesserviceswhen the package has no client-side services andconnecttakes none.@internalandstripInternalNo tsconfig in this repo sets
stripInternal(runtime,tsconfig.generated.json, std-extra, and the generated libtsconfig.json). A consumer's can, and then the marked declarations drop out of their emitted.d.ts. So I checked what that removes:*Paramsinternal breaks it:Admin.greet(peer, params: AdminGreetParams)andAdminSender.greetname it, and the stripped declaration fails withTS2304: Cannot find name 'AdminGreetParams'(reproduced). The issue lists*Params; I left them unmarked because they are API: the interface a user implements names them.Layout(NoticeLayout): other packages import it by name (import { NoticeLayout } from ...). Only the params layouts (*ParamsLayout) are marked, since nothing outside the file names them.npm run typecheck:stripped(new, in theruntime - Nodejob) emits declarations of the generated fixtures with--stripInternaland type-checks them withskipLibCheck: false. JS output is unaffected bystripInternal. The header comments avoid the literal marker text so a header never attaches to the firstimportas an internal declaration.No import cycle
connection.tsimports every protocol file (it builds their dispatchers), so having protocol files importFormatfrom it would be a cycle.wire.tsimports only the runtime (and a third-party codec's package), so nothing cycles.No wire change
runtime/test/wire-invariance.test.ts(first commit, recorded from the generator before any change, then compared after) reads every blessed fixture and records, per package: each file'sIR_HASH; the package'sCONNECTION_IR_HASH(one value, wherever it is defined);HELLOas hex; the codecFormatis built from; each protocol'sPROTOCOLnumber; every*_CALLStable; and every call's id and name a sender writes or a dispatcher takes. 17 packages (nested, services, hello, clash, collisions, dependency, reserved, bounds, link, link_jsonrpc, comline2/{old,new,alien}, chat, acme, acme-encodings). After the change the record differs from the baseline only by:bounds,linkandlink_jsonrpc, which moved into directories (below);link_jsonrpc/now lists the codecPackedCodec, because its previously unblessedwire.tsis now part of the fixture (the package's declared format; the framing still writes JSON).The generator's own tests also check the digest in
wire.tsagainstconnections::connection_ir_hash.Goldens
Re-blessed with
TS_BLESS=1; every diff reviewed. The only changes:@internalmarkers; protocol files lose theirCONNECTION_IR_HASH/Formatdefinitions and the then-unusedPackedCodecimport (lockstep ones importFormatfromwire.js);provideOndocs gain "(FormatandCONNECTION_IR_HASHare in./wire.js)" where a protocol file points at them;connection.tsgains the header, re-export andconnectdoc; newwire.tsper package.bounds,linkandlink_jsonrpcused to keep only the protocol file; with awire.tsthe files go together, so they moved totest/generated/bounds/,link/,link_jsonrpc/(which now also type-checks theirconnection.ts).std-extrais unchanged (xtask --check).Lines, before / after (whole package): nested 214 / 236, services 421 / 442, comline2/new 256 / 280,
chat.ts(lockstep) 180 / 184. The protocol files shrink (nested/chat/admin.ts109 / 103,services/game.ts174 / 171); the package grows bywire.tsand the header.Shortening long types
Looked at the async and JSON-RPC shapes (
link*.ts): TypeScript's signatures already use the runtime's short names (Peer,Transport,Promise<T>);asyncchanges nothing in the TypeScript output (a test pins that). The only long lines are doc comments, which a type alias doesn't help. No alias added; if there's a specific signature to shorten, say which.After merge
generation's
conformance/tests/golden/*/typescript/need re-blessing with this output (separate follow-up there; not touched here). cli and other repos untouched.