Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Duncanma
added
the
blocked-on-release
| --- | ||
|
|
||
| A [Nexus Service](/nexus/services) is a contract meant to be shared across team boundaries. | ||
| Those teams often work in different languages, so the same request and response types get hand-written once per SDK. |
There was a problem hiding this comment.
once -> for each.
We are trying to make it sound annoying, but it reads like "just once for each sdk" which makes it seem like not a big deal.
| :::caution | ||
|
|
||
| `nexgen` is pre-release software, currently at version 0.2.1. | ||
| The supported schema subset, command-line options, and emitted code may change incompatibly before a stable release. |
There was a problem hiding this comment.
This phrasing was hard to understand. May not retain backwards compatibility with previous versions of the tool
| - **A shared runtime validator.** One validator per type, used when a value is parsed off the wire and again when it is serialized onto the wire, so a payload cannot enter or leave your service in a shape the contract forbids. | ||
| - **A [Nexus Service Contract](/glossary#nexus-service-contract) definition.** The generated Service and Operation declarations you register on a Worker and call from a caller Workflow. | ||
|
|
||
| Constraint failures do not surface one at a time. |
There was a problem hiding this comment.
This is an interesting placement because it is not what the generator produces but is a behavior of the generator.
| A handler maps that error to a `BAD_REQUEST` [Nexus error](/nexus/error-handling), so a malformed request tells the caller everything that was wrong with it in one response. | ||
|
|
||
| The supported schema subset is deliberately strict. | ||
| Anything ambiguous, or anything that cannot be expressed identically in all four languages, is rejected when you run the generator, with a diagnostic explaining how to express it instead. |
There was a problem hiding this comment.
all four languages -> all supported languages.
(because this number can change, and also you never listed the 4 prior to this line)
| required: [messageId] | ||
| ``` | ||
|
|
||
| `fqn` is the wire name of the Service, the name callers reference when executing an Operation. |
There was a problem hiding this comment.
Could us a context note to say Let's explain some of the key elements of the payload. I had no idea what fqn was referencing for a minute when I saw this.
|
|
||
| ## Install the generator | ||
|
|
||
| Build the `nexgen` binary from source with a Rust toolchain: |
There was a problem hiding this comment.
Does it have to be Rust tool chain, or just because that is what our example shows. Would be good to clarify.
| ```bash | ||
| git clone https://github.com/temporalio/nex-gen.git | ||
| cd nex-gen | ||
| cargo build --release |
There was a problem hiding this comment.
what is cargo, and how do I get it if I want to use this project.
| --package-name com.example.chat | ||
| ``` | ||
|
|
||
| If the two disagree, generation stops and tells you how to reconcile them: |
There was a problem hiding this comment.
I'm conflicted on this, this seems like a helpful tip if we expect folks to hit is a lot, but also could be an extraneous detail
| nexgen ts samples/schemas/temporal.yaml --output ./chat --date-time-types temporal | ||
| ``` | ||
|
|
||
| - `string` (the default) keeps every temporal field as the RFC 3339 string that appears on the wire. |
There was a problem hiding this comment.
What the heck is an RFC 3339 string? Is it important to qualify it as a "RFC 3339" string? If so, hyperlink to the RFC
| - `string` (the default) keeps every temporal field as the RFC 3339 string that appears on the wire. | ||
| It has no runtime dependency and round-trips losslessly, but you parse and compare the strings yourself. | ||
| - `date` maps `date-time` fields to a JavaScript `Date`. | ||
| This is lossy: a `Date` is a UTC instant, so the original offset is folded away and precision is capped at milliseconds. |
There was a problem hiding this comment.
We're not using ISO-8601? https://en.wikipedia.org/wiki/ISO_8601
I thought the whole world uses ISO-8601... ?
| It has no runtime dependency and round-trips losslessly, but you parse and compare the strings yourself. | ||
| - `date` maps `date-time` fields to a JavaScript `Date`. | ||
| This is lossy: a `Date` is a UTC instant, so the original offset is folded away and precision is capped at milliseconds. | ||
| - `temporal` maps to the TC39 Temporal API, preserving offset and sub-second precision, and requires the `Temporal` global or a polyfill. |
There was a problem hiding this comment.
What is the TC39 Temporal API?
| This is lossy: a `Date` is a UTC instant, so the original offset is folded away and precision is capped at milliseconds. | ||
| - `temporal` maps to the TC39 Temporal API, preserving offset and sub-second precision, and requires the `Temporal` global or a polyfill. | ||
|
|
||
| ## Use the generated code |
There was a problem hiding this comment.
This is strange use generate code talks about how the validation works, and then jumps into the generated code samples. It should do one or the other, either explain how the generated code was generated, or deep dive into a sample. Not both.
|
|
||
| ## Supported schema features | ||
|
|
||
| The generator implements a curated subset of JSON Schema 2020-12 chosen so that every accepted construct lowers identically into all four languages. |
There was a problem hiding this comment.
Why are we so in love with writing out: JSON Schema 2020-12. Is that meaningful to folks rather than just say Json Schema.
There was a problem hiding this comment.
Also, don't say all four languages.
4 participants
This is documentation for pre-release code, do not merge yet!
┆Attachments: EDU-6905 Adding documentation for Nexus Client library code generation