Skip to content

Generated TypeScript: name the entry points, mark the plumbing internal, define shared constants once - #172

Merged
Kinflou merged 2 commits into
mainfrom
feat/generated-entry-points
Nov 14, 2026
Merged

Kinflou merged 2 commits into
mainfrom
feat/generated-entry-points

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 14, 2026

Copy link
Copy Markdown
Member

Closes #170.

Generated TypeScript now says where to start, marks the wire plumbing @internal, and defines Format / CONNECTION_IR_HASH once. No wire byte, number or hash changes.

What changes in the output

Entry points. connection.ts and, in lib mode, the root src/index.ts (with @packageDocumentation) open with a header naming what to implement, serve, dial and call for the package's shape:

/**
 * Where to start:
 *
 * - Implement what you provide: `Admin` (in `./chat/admin.js`).
 * - Serve with `serve(transport, { admin })`; `accept(transport, { admin })` takes the same and hands back the connection.
 * - Dial with `connect(transport)`.
 * - Call the other end with `new AdminSender(conn).greet(…)`, on the connection `connect` returns or the peer a handler is given.
 *
 * What is marked internal is wire plumbing: exported for hand-written use, and not what
 * a user calls.
 */

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>Dispatcher the package's Services / ClientServices builds. A lockstep dispatcher (nothing covers it) stays public.

Format and CONNECTION_IR_HASH live in a new wire.ts when more than one file would define them (every protocol file that needs one, plus connection.ts). Protocol files drop their copies and import Format only where a lockstep helper uses it; connection.ts imports and re-exports both, so connection.Format still works. A package with a single defining file keeps its own, so chat.ts is unchanged apart from the markers. A schema named wire is refused, as one named connection is.

Doc fix. connect's comment no longer says it provides services when the package has no client-side services and connect takes none.

@internal and stripInternal

No tsconfig in this repo sets stripInternal (runtime, tsconfig.generated.json, std-extra, and the generated lib tsconfig.json). A consumer's can, and then the marked declarations drop out of their emitted .d.ts. So I checked what that removes:

  • Marking *Params internal breaks it: Admin.greet(peer, params: AdminGreetParams) and AdminSender.greet name it, and the stripped declaration fails with TS2304: Cannot find name 'AdminGreetParams' (reproduced). The issue lists *Params; I left them unmarked because they are API: the interface a user implements names them.
  • Same for a type's 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.
  • Everything marked is referenced by no exported signature, so stripping it leaves the declarations valid.

npm run typecheck:stripped (new, in the runtime - Node job) emits declarations of the generated fixtures with --stripInternal and type-checks them with skipLibCheck: false. JS output is unaffected by stripInternal. The header comments avoid the literal marker text so a header never attaches to the first import as an internal declaration.

No import cycle

connection.ts imports every protocol file (it builds their dispatchers), so having protocol files import Format from it would be a cycle. wire.ts imports 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's IR_HASH; the package's CONNECTION_IR_HASH (one value, wherever it is defined); HELLO as hex; the codec Format is built from; each protocol's PROTOCOL number; every *_CALLS table; 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:

  • the keys of bounds, link and link_jsonrpc, which moved into directories (below);
  • link_jsonrpc/ now lists the codec PackedCodec, because its previously unblessed wire.ts is 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.ts against connections::connection_ir_hash.

Goldens

Re-blessed with TS_BLESS=1; every diff reviewed. The only changes: @internal markers; protocol files lose their CONNECTION_IR_HASH / Format definitions and the then-unused PackedCodec import (lockstep ones import Format from wire.js); provideOn docs gain "(Format and CONNECTION_IR_HASH are in ./wire.js)" where a protocol file points at them; connection.ts gains the header, re-export and connect doc; new wire.ts per package. bounds, link and link_jsonrpc used to keep only the protocol file; with a wire.ts the files go together, so they moved to test/generated/bounds/, link/, link_jsonrpc/ (which now also type-checks their connection.ts). std-extra is 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.ts 109 / 103, services/game.ts 174 / 171); the package grows by wire.ts and 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>); async changes 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.

Kinflou 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
Kinflou marked this pull request as ready for review November 14, 2026 23:34
@Kinflou
Kinflou merged commit e75fc79 into main Nov 14, 2026
41 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.

Generated code: name the entry points, mark the plumbing internal, define shared constants once

1 participant