github.com/crossnokaye/goa-typescript provides:
plugin/typescript/: a Goa v3 codegen plugin that generates a TypeScript client intogen/ts, straight from the design expressions (no OpenAPI step).runtime/: the small TypeScript runtime that the plugin copies into every generated client (fetch client, response decoding, typed goa errors, Zod codecs, Server-Sent Events, WebSocket streams).
The generated client is functional (fn(client, payload?, options?)), returns Result values instead of throwing, types goa errors by name, and pairs every design type with a Zod 4 schema of the same name.
Status: REST, Server-Sent Events and WebSocket endpoints are generated today, and types and schemas for every HTTP endpoint, with opt-in TanStack Query options. Multipart requests and file servers are on the roadmap.
goa-typescript targets Goa v3.34.x (Go 1.26+). The generated code needs TypeScript 5.6+ and zod ^4.1.0.
The Goa plugin model is: your plugin must be linked into the generator binary that runs during goa gen (plugin guide).
- Add a blank import in your design module (any file in the design package):
import _ "github.com/crossnokaye/goa-typescript/plugin/typescript"- Run generation:
# IMPORTANT: your `goa` CLI must be compatible with the `goa.design/goa/v3` module
# version used by your repo. If you see a compile error like:
# "not enough arguments in call to generator.Generate"
# it means your installed `goa` binary is older/newer than the module.
#
# This repo pins goa to v3.34.0, so this is a safe invocation:
go run goa.design/goa/v3/cmd/goa@v3.34.0 gen <design-import-path> -o .
# or, if your module declares goa as a tool:
go tool goa gen <design-import-path> -o .- Install the generated package's dependencies.
goa gendeletes everything undergen/,gen/ts/node_modulesincluded, so do this after every generation:
pnpm installDesign metadata the plugin reads:
| Meta | Where | Effect |
|---|---|---|
Meta("typescript:package", "@repo/api") |
API |
npm package name (default <api-name>-client) |
Meta("typescript:generate", "false") |
Service, Method |
leaves the service or method out |
Meta("typescript:name", "Thing") |
Type, ResultType |
TypeScript name of the type |
Meta("typescript:name", "ColorKey") |
an inline primitive, enum, array, map or union attribute | hoists the attribute as a named type and schema (see Models and schemas) |
Meta("typescript:query", "tanstack") |
API |
generates TanStack Query options beside every function (see TanStack Query) |
Meta("typescript:query:kind", "query") |
Method |
classifies the method as query, mutation or none for TanStack Query |
Meta("typescript:invalidates", "list_things, get_thing") |
Method |
the methods whose keys a mutation invalidates; "" for none |
gen/ts/
├── package.json name from Meta("typescript:package"); "type": "module"; peer dependency on zod
├── tsconfig.json strict, bundler module resolution; used by the package's own `type-check` script
└── src/
├── index.ts re-exports the runtime, the types, and one namespace per service
├── types.ts every type the design declares, each with its Zod schema
├── runtime/*.ts the runtime, copied verbatim
└── <service>/
├── index.ts barrel for the service
└── <method>.ts one function per method: its request type, error table, error union
(two functions when the method offers both a plain result and a stream),
then its TanStack Query options with Meta("typescript:query", "tanstack")
The package is TypeScript source, not a build: package.json exports point at .ts files, and relative imports use the .js suffix that bundler module resolution maps back to them.
import { createClient, toy, unwrapAsync, type Thing } from 'toy-client';
import { streamThingsSse } from 'toy-client/toy'; // same function, importable on its own
import { Thing as ThingSchema } from 'toy-client/types';import { createClient } from 'toy-client';
const client = createClient({
baseURL: 'https://api.example.com', // a path prefix is kept; a relative URL works in a browser
auth: () => getAccessToken(), // string or function, sync or async, asked on every call
timeoutMs: 10_000, // bounds the wait for response headers (or for a WebSocket to open); streams are not cut off
headers: { 'X-Client': 'web' },
// webSocket: (url, protocols, init) => ..., // replaces the global WebSocket; see Streaming methods (WebSocket)
middleware: [
async (req, next) => {
const res = await next(req);
console.debug(req.method, req.url, res.status);
return res; // read res.clone(), never res itself: the body belongs to the caller
},
],
});Middleware wraps fetch, so it applies to REST and SSE functions; a WebSocket has no Request or Response to hand it.
Credentials. The attributes a design marks with Token, AccessToken, APIKey, Username and Password are left out of the request types. The client fills them in from auth, in the header or query parameter the design maps them to:
- a bare provider is used for every security scheme;
auth: { jwt: getToken, api_key: 'k' }selects a provider by scheme name;- a provider that returns
undefinedsends the request without that credential; - a bearer token gets the
Bearerprefix unless it already contains a space; basic credentials areusername:password.
Methods declared with NoSecurity() never receive a credential.
Per-call options are the last argument of every function: signal, headers, timeoutMs, baseURL, and any other RequestInit field (cache, credentials, ...). A WebSocket function takes signal, headers, timeoutMs, baseURL and protocols.
One call shape. Every function is fn(client, payload?, options?), whatever the method declares (ADR 0003). The payload is always the second argument:
| Design | payload |
|---|---|
a Payload with a required attribute (credentials do not count: they come from the client's auth) |
required |
a Payload whose attributes are all optional or have a Default |
optional; fn(client) sends an empty payload |
no Payload, or nothing left of it once credentials are stripped |
undefined; fn(client) or, to pass options, fn(client, undefined, { signal }) |
So a wrapper typed (client, payload, options?) => Promise<CallResult<Res, EndpointError>> accepts every function, and adding the first optional attribute to a method does not change how its callers look. Passing options to a payload-less method takes an undefined placeholder; passing them where the payload goes is a compile error rather than a silently misread request. The one exception is a raw upload without a payload: body follows payload, and an optional parameter cannot precede a required one, so payload is a required undefined there.
A method without streaming becomes a function fn(client, payload?, options?) that resolves to the method's result:
import { toy } from 'toy-client';
const result = await toy.getThing(client, { id: 'abc' }, { signal });
if (!result.ok) {
return handle(result.error); // see Errors
}
result.value; // ThingReply: decoded and validated, dates already Date objects
result.response.status; // the fetch Response, for the status and the headers
result.response.headers.get('etag');
await toy.getThingViewed(client); // every attribute is optional: the payload may be omitted
await toy.listThings(client, undefined, { signal }); // no payload: undefined holds its placeThe value is the bare goa type. There is no { data } envelope: what the design calls the Result is what result.value is, and what unwrapAsync returns. Transport metadata rides beside it, on result.response (ADR 0002). On a failure result.response is set whenever a response arrived (a goa error, an unexpected response, a response that fails validation) and absent otherwise (network failure, abort, timeout, a request that fails validation).
| Design | Function |
|---|---|
Result(Thing) |
value is Thing |
Result(func() { ... }), Result(ArrayOf(String)), Result(Int) |
value has the type <Method>Result, declared in the method's file |
Result(CollectionOf(Thing)) |
value is Thing[]; goa's ThingCollection name is not used |
no Result |
value is void |
Header("etag:ETag") in a Response |
the attribute is filled from the header: numbers and booleans are parsed, arrays are split on commas |
Cookie(...) in a Response |
the attribute is never set: script cannot read Set-Cookie |
Body("attr") |
the body is that attribute |
several Responses |
one value type; result.response.status says which response it was |
Tag("outcome", "created") |
the client sets outcome to 'created' for that response, as goa's Go client does |
Several statuses. goa picks the response from the result's tag attribute and leaves that attribute out of the body. The client puts it back, so both views agree:
const result = await toy.upsertThing(client, { id, name });
if (result.ok) {
result.response.status; // 200 or 201
result.value.outcome; // 'updated' or 'created'
}A response without a body is decoded from its headers and tag alone. If the result type requires an attribute that such a response does not carry, the response cannot be valid: goa gen prints a warning, the function's documentation says so, and at run time that status fails with a ResponseValidationError. Make the attribute optional in the design, or give the response a body.
Raw download (SkipResponseBodyEncodeDecode). The value is built from the mapped headers and the body is left unread on the response. This is the one case where result.response still has its body:
const result = await toy.downloadThing(client, { id });
if (result.ok) {
result.value.content_length; // from the Content-Length header
const blob = await result.response.blob(); // or arrayBuffer(), or result.response.body to stream it
}Raw upload (SkipRequestBodyEncodeDecode). The function takes the body after the payload and hands it to fetch as is:
await toy.uploadThing(client, { id, content_type: file.type }, file);When the method has no payload the function still takes one, typed undefined, so that body stays in its place: upload(client, undefined, file). The same holds for a raw upload whose payload attributes are all optional: payload stays required there, because TypeScript does not allow an optional parameter before a required one.
A Blob (so a File), an ArrayBuffer, FormData and a string work everywhere. A ReadableStream is sent with duplex: 'half', which Safari and Firefox do not support. No Content-Type is set unless the design maps a payload attribute to that header; fetch derives one from a Blob or a string.
A plain result and a stream (Result and StreamingResult on one method). Two functions in one file: streamOrList() sends Accept: application/json and returns the plain result, streamOrListStream() is the SSE function. They share the request type and the error union.
Not generated, and listed with the reason at the bottom of the service barrel: Redirect(...) endpoints (fetch follows the redirect, so there is nothing to return), responses with a non-JSON ContentType that are not raw, response headers of type Bytes or Any (goa does not write them in a form the schema can read back), a raw request body on GET or HEAD, multipart and form-encoded requests, file servers.
Things worth knowing:
- Cross-origin headers. A browser shows script only a short list of response headers from another origin. Unless the UI and the service share an origin, the service must list every header a design maps to an attribute, plus
goa-errorandgoa-view, inAccess-Control-Expose-Headers. Withoutgoa-errorthe name of an error is still read from the body of goa's default error type; a custom error type that shares its status code with another error cannot be told apart. voidand TanStack Query.unwrapAsync(toy.deleteThing(...))resolves toundefined. That is right foruseMutation. AuseQueryqueryFnmust not resolve toundefined: return something else from it. The generated query options of a read without a result resolve tonullfor that reason.- A 200 that is not JSON (a proxy's login page, say) is an
UnexpectedResponseErrorcarrying the text, not a validation error. nullfor an empty array or map. A Go service encodes a nil slice or map result asnull; the client reads it as empty.- Array headers are split on commas, so an element that contains one does not survive. goa has the same limit on the way in.
A method with StreamingResult and ServerSentEvents() becomes a function fn(client, payload?, options?), shaped like a REST function, that resolves to an async-iterable EventStream:
import { toy } from 'toy-client';
const result = await toy.streamThingsSse(client, { id: 'abc' }, { signal });
if (!result.ok) {
return handle(result.error);
}
for await (const event of result.value) {
render(event.thing); // typed, validated, dates already Date objects
}
// The loop ends when the server closes the stream.- The stream yields the method's whole event type. Attributes that the design maps with
SSEEventID,SSEEventTypeandSSEEventRetryare filled from the frame. stream.lastEventIdandstream.retryexpose the most recentid:andretry:values.- Leaving the loop (
break,return, an exception) or callingstream.close()cancels the response. - An event that does not match its schema throws
ResponseValidationErrorfrom the loop and closes the stream. AbortingsignalthrowsAbortError. - Errors the server reports before the first event are ordinary typed errors in
result.error. - The result carries the fetch
Responselike any other function's:result.response, which is alsoresult.value.responseonce the stream is open.
There is no automatic reconnection. The stream is a plain fetch response (so it can send headers and POST bodies, unlike EventSource), and when to reconnect is the application's call. Resume by passing the last event ID back; the client sends it as Last-Event-ID:
let lastEventId: string | undefined;
while (!signal.aborted) {
const result = await toy.streamWrappedSse(client, { id }, { signal, lastEventId });
if (result.ok) {
try {
for await (const { data } of result.value) {
render(data);
lastEventId = result.value.lastEventId;
}
} catch (e) {
if (signal.aborted) break;
report(e);
}
} else if (result.error.kind === 'goa' && !result.error.temporary) {
throw result.error; // not worth retrying
}
await sleep(backoff());
}When the design names the payload attribute that carries the ID (SSERequestID("last_event_id")), that attribute is left out of the request type: options.lastEventId supplies it.
A method that streams over a WebSocket (it declares a StreamingPayload, or a StreamingResult without ServerSentEvents()) becomes a function fn(client, payload?, options?), shaped like the others, that resolves once the socket is open to a WebSocketStream<Recv, Send> (ADR 0005):
import { toy } from 'toy-client';
const result = await toy.echoWs(client, { prefix: '>' }, { signal });
if (!result.ok) {
return handle(result.error); // a NetworkError when the server refused the connection
}
const stream = result.value;
stream.send({ text: 'hello' }); // validated and encoded; returns a Result, never throws
stream.end(); // nothing more to send: goa's end-of-stream null; returns a Result too
for await (const reply of stream) {
render(reply); // typed, validated, dates already Date objects
}
// The loop ends when the server closes the connection with code 1000.| Design | Recv (what the loop yields) |
Send (what send takes) |
|---|---|---|
StreamingResult(T) |
T |
never: send does not type-check |
StreamingPayload(P), StreamingResult(T) |
T |
P, on its request side (PRequest when it has defaults) |
StreamingPayload(P), Result(T) |
T: one value, after end() |
P |
StreamingPayload(P) and no result |
never |
P |
An unnamed type is declared in the method's file as <Method>Result or <Method>StreamingPayload.
- The
Payloadtravels in the upgrade request, aGET: path and query parameters (goa allows no body there). - Every message is one JSON text frame. A message the server sends that does not match its schema throws
ResponseValidationErrorfrom the loop and closes the socket.sendreturns the validation error of a message that does not match, and sends nothing; on a closed socket it returns aNetworkError. end()sends the JSONnullwith which a goa client ends its stream; the socket stays open for what the server sends next. It returns aResultlikesend: aNetworkErrorwhen the socket is no longer open. Calling it again does nothing, andsendfails after it with aNetworkError, since goa's server reads nothing after thenull. A client-streaming method answers with its one result, then the loop ends (goa drops that connection without a close frame; the stream knows to expect it).- The loop ends when the server closes with code 1000, the way goa ends a stream, and when the client closes:
stream.close(code?, reason?), leaving the loop (break,return, an exception), or abortingsignal, which closes with 1000 and throwsAbortErrorfrom the loop. Any other close throws aNetworkErrorwhosecloseCodeandcloseReasonsay why. stream.closedresolves with{ code, reason, wasClean }once the socket is closed;stream.socketis theWebSocketitself.timeoutMsbounds the wait for the socket to open (TimeoutError); an open socket is never cut off.- The URL is the endpoint's with
http:andhttps:turned intows:andwss:. A relativebaseURLresolves against the page's location.
What a browser WebSocket cannot do, and what the client does about it:
-
No headers. The browser API sends no custom header. Credentials the design maps to the query string, like
Param("key:api_key")for an API key, work as for any function. Credentials mapped to a header (a JWT inAuthorization, the default; an API key header; basic auth) and payload attributes mapped withHeader(...)are not sent: the function's documentation lists them. In a browser, map the credential to a query parameter or authenticate with a cookie. Elsewhere, setClientOptions.webSocket, a factory that replaces the globalWebSocketthe wayfetchreplaces the global fetch; its third argument carries the headers the call would send:import WebSocket from 'ws'; const client = createClient({ baseURL, auth: getToken, webSocket: (url, protocols, { headers }) => new WebSocket(url, protocols, { headers: Object.fromEntries(headers) }) as unknown as globalThis.WebSocket, });
Node 22 and later have a global
WebSocket(undici's), used by default, whose constructor also takes{ protocols, headers }as its second argument. -
No handshake response. When the server refuses the upgrade, with an error the design declares or any other HTTP response, the browser reports only that the connection failed. The function returns a
NetworkError, never a typedGoaError: its error union isRequestValidationError | TransportError, and the errors the design declares are listed in its documentation instead. For the same reasonresult.responseis a stand-in, an empty200Response. -
No view. goa names the view of a viewed result in the
goa-viewheader of the upgrade response, which script cannot read. Attributes that some view leaves out are optional in the generated type, so every view decodes. -
No middleware, which wraps
fetch.
Not supported: reconnection (call again), binary frames (goa sends text), backpressure (stream.socket.bufferedAmount is there to read), ping and pong (the browser answers pings on its own). A client-streaming method whose Response sends the result as one attribute (Body("total")) is not generated, and listed at the bottom of the service barrel.
With Meta("typescript:query", "tanstack") on the API, the generated functions also get TanStack Query v5 options: plain objects to hand to useQuery, useMutation, queryClient.fetchQuery and the like (ADR 0006). Without the meta nothing changes in the generated functions; the runtime's query.ts ships in every client either way, and a bundler drops it when nothing uses it.
var _ = API("toy", func() {
Meta("typescript:query", "tanstack")
})Nothing in the generated package imports TanStack: the runtime (runtime/query.ts) declares the shapes TanStack accepts structurally, and the toy's tests prove them against @tanstack/query-core. Each method's exports sit at the end of its own file, src/<service>/<method>.ts, after its function, so they are re-exported by the service barrel with it; the transport mapping they use stays private to that file. They are one line each calling a runtime helper, and each carries a JSDoc state card: who owns the data (the server), the key it lives under, that it is not writable, and which generated mutations invalidate it.
| Method | Exports | Returns |
|---|---|---|
GET, HEAD |
getThingQuery(client, payload), getThingKey(payload?) |
{ queryKey, queryFn }; the key |
| Server-Sent Events, server-streaming WebSocket | streamThingsSseQuery(client, payload, { streamedQuery, ... }), streamThingsSseKey(payload?) |
{ queryKey, queryFn, staleTime: Infinity }; the key |
| every other verb, raw uploads included | createThingMutation(client, { queryClient? }), createThingInvalidates(variables?) |
{ mutationFn, onSuccess? }; the keys it invalidates |
| a mixed method | streamOrListQuery/streamOrListKey and streamOrListStreamQuery/streamOrListStreamKey |
a query and a stream |
Meta("typescript:query:kind", "query" | "mutation" | "none")on aMethodoverrides the classification: aPOSTthat only reads becomes a query, a method can opt out.goa genfails on an override that cannot work (a query over a bidirectional WebSocket, a raw upload or a raw download).- A
GETorHEADwithout aResultresolves tonull, notundefined, which TanStack Query treats as an error: its data is typednull. - No options are generated for raw downloads (
SkipResponseBodyEncodeDecode: the body is left on the response), WebSocket methods that stream a payload, and the methods the SDK skips. The service barrel lists them with the reason.
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import { toy } from '@repo/api';
const { data } = useQuery(toy.getThingQuery(client, { id }));
const queryClient = useQueryClient();
const upsert = useMutation(toy.upsertThingMutation(client, { queryClient }));Keys. A key is the path of the route, split on /, with each parameter replaced by its value, then one object holding every other input: query parameters and header parameters under their request property names, map query entries, the JSON body's properties. Values are in wire form (a Date is its RFC 3339 string), so keys are stable and serializable. The object is left out when there is nothing in it; an attribute set to undefined is left out of it. A stream's key always has the object, with $stream: true first.
toy.getThingKey({ id: 'abc', tags: ['x'], verbose: true }); // ['things', 'abc', { tags: ['x'], verbose: true }]
toy.getThingKey({ id: 'abc' }); // ['things', 'abc']
toy.listThingsKey(); // ['things']
toy.streamThingsSseKey({ id: 'abc' }); // ['things', 'abc', 'events', { $stream: true }]
toy.getThingKey(); // ['things']: an invalidation prefix, not a cache key
toy.streamOrListStreamKey(); // ['stream-or-list', { $stream: true }]xyzKey() without a payload is an invalidation prefix, which matches every key of the method. For a route with parameters it is the static segments before the first one (['things']), which other methods under the same path share: use it with invalidateQueries or cancelQueries, never with setQueryData. For a route without parameters it is the route followed by the key's markers when it has some ($stream, $method), so that it is no other query's exact key: streamOrListStreamKey() is not streamOrListKey(). A route that starts with a parameter gets the route with null for each one, never the empty key.
Credentials never enter a key (they are not in the request types), nor does anything of the client such as its base URL: a key names the data, not who asked for it or where. The service name does not either, so two services that serve the same path share keys, as they share URLs. A payload that fails validation gets a key no real request has, the route with null for each parameter and a trailing { $invalid: true } (['things', null, { $invalid: true }]), and its queryFn rejects with the RequestValidationError; it never takes over the cache entry of another query, such as the list under the same prefix.
Dependent queries. When the design requires a payload, getThingQuery(client, undefined) is accepted too and returns a disabled query (enabled: false) whose key is the route with null for each parameter and a trailing { $disabled: true } (['things', null, { $disabled: true }]), so that it never reads data cached for another query, even for a route without parameters whose bare path is another method's key:
const found = useQuery(toy.findThingQuery(client, { name }));
const thing = useQuery(toy.getThingQuery(client, found.data?.match ? { id: found.data.match.id } : undefined));An optional payload may be omitted (toy.listThingsQuery(client)) and a method without one takes nothing, as in one call shape. No other option is set on a read (staleTime, retry, gcTime are the application's defaults); spread the object to add some: useQuery({ ...toy.getThingQuery(client, { id }), staleTime: 30_000 }).
Streams. A stream query wraps TanStack's streamedQuery, which the caller passes in:
import { experimental_streamedQuery as streamedQuery, useQuery } from '@tanstack/react-query';
const { data: events } = useQuery(toy.streamThingsSseQuery(client, { id }, { streamedQuery }));
const { data: count } = useQuery(
toy.watchTicksQuery(client, { id }, { streamedQuery, reducer: (sum, tick) => sum + tick.n, initialValue: 0 }),
);- The generated code does not import
streamedQuerybecause it does not import TanStack at all: the package keepszodas its only dependency, and the helper is stillexperimental_in TanStack, so the application picks the version it runs. It needs TanStack Query 5.86 or later, wherestreamedQuerytakesstreamFn,reducerandinitialValue(earlier releases named the functionqueryFn). - The payload is a required parameter (
undefinedfor a method without one, or to disable a stream whose payload the design requires), because the options follow it. staleTimeisInfinity: an open stream is never stale, and a refetch would reopen it.- Mutations never invalidate a stream.
invalidateQueriesrefetches every active query it matches whatever itsstaleTime, which for a stream means aborting it and opening it again from the start. The generatedonSuccesspasses apredicatethat skips every key carrying$stream; a stream shows new data through its own events. Invalidate one by hand with its key if that is what you want. - A refetch is not a resume. It opens a new stream from the start;
refetchMode('reset'by default,'append','replace') only says what happens to the data already there. For an SSE stream that can resume, use the function itself withlastEventId(SSE). - The data grows without bound. By default every event is appended to an array for as long as the stream is open. For a long-lived stream, pass a
reducer(with itsinitialValue) that keeps what the screen needs: the latest value, a count, a bounded window. The reducer's second argument is typed as the method's event. - Errors. An error before the first event (a goa error, a refused connection) fails the query like any other. An error mid-stream (a message that fails validation, a dropped connection) fails it too, with the events received so far still in the cache. Unmounting, or
queryClient.cancelQueries, aborts the signal and closes the connection.
Mutations. createThingMutation(client) returns { mutationFn }, which calls the function and throws its error; a raw upload's variables are { payload, body }. Given { queryClient }, it also returns an onSuccess that invalidates the keys the mutation affects and waits for them:
- by default, the nearest key under which a read lives: start from the mutation's own route with trailing parameters stripped, then drop the last segment until some
GET/HEAD(or read-overridden) method's route starts with it, never below one segment.PUT /things/{id}andPOST /thingsinvalidate['things'];DELETE /things/{id}/labels/{lid}andPUT /things/{id}/contentinvalidate['things', id], withidtaken from the variables, when no read lives underlabelsorcontent. When no read lives under any of them, the mutation keeps the one-segment key,goa genwarns (mutation "x" invalidates no query) and the state card says so; Meta("typescript:invalidates", "list_things, get_thing")on the method replaces the default with the keys of the methods it names (queries or streams of the same service;goa genfails on any other name). Each named route is kept whole, its parameters filled in from the mutation's own path parameters of the same name:PUT /sites/{site_id}/modenamingget_plan(GET /sites/{site_id}/plan) invalidates['sites', site_id, 'plan']for that site only. Body and query properties are not used, even under the same name. The key stops before the first parameter the mutation's path lacks, falling back to a shorter prefix;goa genwarns (mutation "x" has no path parameter {p} to fill in the route of "y") and the state card shows where the key stops. A named route that starts with a parameter the mutation's path lacks has no prefix left, andgoa genfails. An empty string invalidates nothing.
Stream keys are never invalidated, whatever the list says (see Streams). A key that would be empty is dropped rather than sent, since it would match every query.
createThingInvalidates(variables) returns the same keys for wiring invalidation by hand. To write the result into the cache as well, spread the options and call the generated onSuccess from yours:
const options = toy.upsertThingMutation(client, { queryClient });
useMutation({
...options,
onSuccess: async (result, variables) => {
queryClient.setQueryData(toy.getThingKey({ id: variables.id }), result);
await options.onSuccess?.(result, variables);
},
});Collisions. Two reads, or two streams, whose routes are the same once parameter names are ignored (/things/{id} and /things/{thing_id}), across every service, would share keys. The GET keeps its clean key; every other member gets $method in its trailing object (['things', 'abc', { $method: 'HEAD' }], after $stream for a stream); when no member is a GET, all of them do. A read and a stream never collide, since every stream key carries $stream: the plain function and the stream of a mixed method keep apart without a discriminator. The state cards say so. A disabled or invalid query keeps its markers first, before its sentinel.
Hooks. None are generated, so the package does not depend on React or pin a TanStack adapter: the options work with @tanstack/react-query, vue-query, solid-query and plain query-core alike. A hook is a one-liner in the application, which also knows where its client comes from:
export const useThing = (id: string | undefined) =>
useQuery(toy.getThingQuery(useApiClient(), id === undefined ? undefined : { id }));Every type the design declares with Type or ResultType gets one TypeScript type and one Zod schema with the same name, the usual Zod idiom:
import { Thing, decode, decodeJSON, encode } from 'toy-client';
const thing: Thing = { id, kind: 'widget', enabled: true }; // the type
const parsed = decode(Thing, json); // the schema: wire -> local, Result<Thing, ...>
const fromText = decodeJSON(Thing, text);
const wire = encode(Thing, thing); // local -> wire, validatedInline types (a Payload(func() { ... }), a nested object, a primitive union branch) are rendered in place; the plugin does not invent names, but the design can give one. Meta("typescript:name", "ColorKey") on an inline primitive, enum, array, map or union attribute hoists it into types.ts as a named type and schema, carrying the attribute's validations, and the parent refers to it:
Attribute("color_key", String, func() {
Enum("blue", "green")
Meta("typescript:name", "ColorKey")
})export type ColorKey = 'blue' | 'green';
export const ColorKey = z.enum(['blue', 'green']) satisfies z.ZodType<ColorKey>;
export type Widget = { color_key: ColorKey; /* ... */ };An inline object attribute cannot be named this way (declare a Type for it; goa gen says so), and a Default stays with the parent, which is what makes the attribute optional on the request side. Without a name, the usual TypeScript idioms reach an inline type: Widget['color_key'] for a required attribute, NonNullable<Routine['presentation']> for an optional one.
| goa | TypeScript | Notes |
|---|---|---|
Boolean, String, Float32, Float64 |
boolean, string, number |
|
Int, Int32, Int64, UInt, UInt32, UInt64 |
number |
checked to be a safe integer: a value past 2^53 fails validation rather than losing precision |
Format(FormatDateTime) |
Date |
RFC 3339 with any offset on the wire |
Format(FormatDate) |
string |
YYYY-MM-DD; never a Date, which would drag a time zone in |
Format(FormatUUID), email, hostname, ipv4, ipv6, ip, cidr |
string |
validated |
Format uri, mac, regexp, json, rfc1123 |
string |
not validated |
Bytes |
Uint8Array |
base64 on the wire; a plain string when sent as a query parameter or header |
Any |
unknown |
|
ArrayOf(T), MapOf(K, T) |
T[], Record<string, T> |
|
Enum(...) |
union of literals | closed: an unknown value fails validation |
OneOf(...) |
{ type: 'a'; value: A } | { type: 'b'; value: B } |
the envelope goa puts on the wire; key names follow oneof:type:field / oneof:value:field |
Pattern, Minimum, MaxLength, ... |
enforced by the schema, on requests and on responses |
Things worth knowing:
- Property names are the wire names. No case conversion: a
created_atattribute iscreated_atin TypeScript.Meta("struct:tag:json", "legacyName")renames the property, as it renames the JSON key. - Optional means absent. goa omits unset optional attributes, so types use
name?: T, nevernull. The one exception goa has is handled for you: astruct:tag:jsonoverride without,omitemptymakes goa sendnull, which decodes to absent. - Defaults. Inside a declared type, an attribute with a
Defaultis not optional: decoding fills it in. In a request it is optional, and omitted from the request, because the server applies the default. For that, every declared type with a defaulted attribute, and every type that refers to one, gets a request-side variant beside it,ThingRequest: the same type and schema with the defaulted attributes optional, referring toOtherRequestwhereThingrefers toOther. Request payloads use the variants, at any depth, so a nested defaulted attribute may be left out too.ThingRequestis also the type for a value built by hand, such as a fixture or a mock, which is why a type no request uses still gets one:encode(ThingRequest, value)sends it as is, and a decodedThingis assignable to it. A type whose request side would not differ has no variant. Results and events keep the decoded type, defaults required. (Migrating from a client that typed defaulted attributes as optional: type the fixtures asThingRequestrather than adding the defaults to each of them.) See ADR 0004. - Views. A result type is one TypeScript type; attributes missing from any of its views are optional.
- Recursive types work (
parent?: Thing). - Unknown attributes are dropped when decoding, so a server can add attributes without breaking deployed clients.
Patterns that only RE2 understands ((?i),(?P<name>,\z, POSIX classes) are not enforced; the schema carries a comment saying so.
Functions never throw. They return CallResult<T, E>, which is a Result<T, E> with the fetch Response beside it:
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
type CallResult<T, E> =
| { ok: true; value: T; response: Response }
| { ok: false; error: E; response?: Response };unwrap(result) and unwrapAsync(promise) turn a failure back into an exception when that is more convenient (inside a TanStack Query queryFn, for instance). They return the bare value.
Every function exports its own error union. EndpointError is the type every union is assignable to, for code that handles errors from more than one endpoint:
import type { EndpointError } from 'toy-client';
type QueryOptions<T> = UseQueryOptions<T, EndpointError>;
function toast(e: EndpointError) { /* ... */ }Every member has a string kind:
kind |
Class | Meaning |
|---|---|---|
'goa' |
GoaError<Name, Detail> |
the service returned an error; name is the goa error name |
'network', 'abort', 'timeout' |
NetworkError, AbortError, TimeoutError |
no response; a WebSocket's NetworkError carries closeCode and closeReason |
'request_validation' |
RequestValidationError |
the request does not satisfy the design; nothing was sent |
'response_validation' |
ResponseValidationError |
the response does not satisfy the design |
'unexpected_response' |
UnexpectedResponseError |
a status or body the design does not describe (a proxy's 502 page, say) |
const result = await toy.streamThingsSse(client, { id });
if (!result.ok) {
const e = result.error; // toy.StreamThingsSseError
if (e.kind === 'goa') {
switch (e.name) {
case 'not_found': // names declared in the design autocomplete
return notFound();
case 'unauthorized':
return signIn();
}
if (e.fault) reportServerBug(e.id, e.message);
}
toast(errorMessage(e));
}GoaError carries goa's id, message, temporary, timeout and fault, plus the HTTP status, headers, parsed body and the response. Errors that goa raises on its own, such as request validation failures, arrive as GoaError too, under names the union cannot list (GoaError<OtherErrorName>). errorMessage(e) renders any of these for display.
Custom error types. An error declared with a type of its own (Error("invalid", ValidationProblem), Error("conflict", func() { ... }), Error("teapot", String)) is decoded and validated into detail. An unnamed type is declared in the method's file as <Method><Error>Detail. Attributes that the error's Response maps to headers are merged in.
Use isGoaError(e, name) to reach the detail. Comparing e.name is not enough for the compiler, because an undeclared error may carry any name:
const result = await toy.createThing(client, { name });
if (!result.ok) {
if (isGoaError(result.error, 'invalid')) {
result.error.detail.field; // ValidationProblem
result.error.detail.retry_after; // from the Retry-After header
}
}The narrowing needs the function's error union to pick from, so it works on result.error. In a catch block the value is unknown: isGoaError(e, 'invalid') still checks the name, and e.detail is unknown.
The generated package is meant to be a workspace member consumed as source:
- Name it:
Meta("typescript:package", "@repo/api")on theAPI. - Add
gen/tstopnpm-workspace.yaml. - Depend on it from the UI package:
"@repo/api": "workspace:*", together with"zod": "^4.1.0". (Zod 4 still shipszod/v3, so code written against Zod 3 keeps working during a migration.) - Regenerate, then
pnpm install: generation wipesgen/ts/node_modules. - With Vite, add the package to
optimizeDeps.exclude; excludegen/ts/**from linting.
- Multipart requests and file servers.
Until then the service barrel lists the methods it skipped, and their types and schemas are generated all the same.