Document how to build a lossless transport - #26
Merged
Conversation
The @lossless section said a lossless transport is required, named the runtime as one, and pointed at parseLossless / stringifyLossless — but in one sentence, with no code and no list of where the substitution has to happen. Since nothing in the generated code can detect a lossy transport, that is the one place where being terse costs a silent bug: the schema validates, the field is a number, and it is the wrong number. So: a "Building a lossless transport" subsection, and a first line that lets anyone using the runtime's fetchTransport stop reading. It enumerates all four JSON boundaries rather than the two obvious ones — request body, response body, *and* per-line ndjson in both directions. All four exist in runtime/src (fetch.ts:90,150,241 and ndjson.ts:21,53), so a transport that fixes only the unary pair still rounds a @lossless member inside a stream. Two specific traps, both from reading the reference implementation: - res.json() cannot be fixed from outside — the rounding happens inside it, before the caller holds the value. Read text() and parse it. - StreamTransportResponse.stream is specified as already-parsed elements, so parsing them losslessly is the transport's job; no later schema can undo it. The doc comment on that field said "already JSON.parse'd", which named the exact function a transport author must not use there. Fixed, and the lossless requirement stated where an implementor will actually read it. Also documents the two body-reading cases that are not about precision but that the generated client depends on — an empty body (204, or no output members) is not valid JSON, and a non-2xx body may not be JSON at all — with the readBody from fetch.ts, since throwing on either turns a useful status into a parse error. Docs and one doc comment; no behaviour change. Runtime typecheck + 46 tests pass.
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
1 participant
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.
The
@losslesssection already said a lossless transport is required, named the runtime as one, and pointed atparseLossless/stringifyLossless. But that was one sentence with no code and no list of where the substitution has to happen — and since nothing in the generated code can detect a lossy transport, this is the one place where being terse costs a silent bug: the schema validates, the field is anumber, and it is the wrong number.So this adds a Building a lossless transport subsection, with a first line that lets anyone using the runtime's
fetchTransportstop reading immediately.What it adds beyond what was there
All four JSON boundaries, not the obvious two. A transport has to substitute on the request body, the response body, and per-line ndjson in both directions. All four exist in the reference implementation (
fetch.ts:90,150,241,ndjson.ts:21,53), so a transport that fixes only the unary pair still rounds a@losslessmember inside a stream.res.json()gets named as a trap. It is the natural way to read a body and it is unfixable from outside — the rounding happens inside it, before the caller ever holds the value. Readtext()and parse that.A doc-comment fix.
StreamTransportResponse.streamis specified as already-parsed ndjson elements, so parsing them losslessly is the transport's job and no later schema can undo it. Its comment said "alreadyJSON.parsed" — naming the exact function a transport author must not use there. Now corrected, with the lossless requirement stated where an implementor will actually read it.Two body-reading cases that aren't about precision but that the generated client depends on: an empty body (204, or an operation with no output members) is not valid JSON, and a non-2xx body may not be JSON at all. Both are shown via
readBodyfromfetch.ts, since throwing on either turns a useful status code into a parse error.On "provide one as a separate module"
Not doing that, and I think the current shape is right:
fetchTransportalready is a provided lossless transport, andparseLossless/stringifyLosslessare already exported from the package root (index.ts) specifically so a hand-rolled transport can use them. A separate module would split two small functions away from their only in-repo consumer without making anything more reachable. The gap was documentation, and that is what this fixes.Docs plus one doc comment; no behaviour change. Runtime typecheck and all 46 tests pass.