apigenie-generator client ws
Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate a TypeScript client of the WebSocket channels of an AsyncAPI document.
Usage
apigenie-generator client ws [...OPTIONS] INPUT_FILE
Description
The input must be an AsyncAPI 3.x document. Documents referencing other files are bundled first.
The generator creates one class per WebSocket channel, i.e. a channel with a ws binding, or a
channel of a server whose protocol is ws or wss (every channel when the document has no
servers). Other channels are skipped. The client uses the WebSocket class of browsers and of
Node.js 22 or later, and has no dependencies.
An AsyncAPI document describes an application. By default the client is its counterpart: it
sends the messages of receive operations and receives the messages of send operations. Set
the perspective option to application to generate the application instead.
import { RoomClient } from "chat-api-client";
const room = new RoomClient();
room.onRoomEvent((event) => console.log(event.kind));
await room.connect({ params: { roomId: "general" }, query: { token } });
room.sendJoin({ type: "join", user });
Each class has:
connect(options): opens the connection. Options are the server (server, a key of the document’s servers, orbaseUrl), the values of server variables (variables), the values of the parameters of the channel address (params), the query parameters of the WebSocket binding (query), handshake headers (headers, see below), the credentials of the channel’s security schemes (credentials, see below), subprotocols (protocols) and awebSocketFactory.send<Message>(payload)for every message the client sends.on<Message>(handler)for every message it receives, when the channel receives one message, or when its messages can be told apart by a property with a distinct constant value (e.g.type: { const: join }).onMessage(handler)receives every message of a channel receiving several. Handlers return a function removing them.request<Operation>(payload, { timeoutMs })for every operation whosereplyis on the same channel, when the request and reply messages have a correlation id in their payloads (e.g.$message.payload#/requestId): it sends the request and resolves with the reply carrying the same id, or rejects aftertimeoutMs(30 seconds by default) or when the connection closes. The reply also reaches itson<Message>handler. OperationrequestPickupgivesrequestPickup,bookPickupgivesrequestBookPickup.onError,onClose,onUnknownMessage,close()andconnected.
Payloads are encoded by the content type of the message: JSON for application/json and
*/*+json (the default), text for text/*, binary data (ArrayBuffer) otherwise.
Browsers can’t send headers with the WebSocket handshake, so the headers option requires a
webSocketFactory creating sockets that can, e.g. of the ws package.
A channel takes the security schemes of its operations, or of its servers for an operation
without any. credentials holds a credential per scheme key: a string, or a function returning
one or a promise of one, called on every connect. The credentials of the first of the channel’s
schemes that has some are sent:
| Scheme | Sent as |
|---|---|
httpApiKey |
the query parameter, header or cookie named by name and in |
http with scheme basic |
the Authorization header, from user:password |
http with scheme bearer, oauth2, openIdConnect |
the Authorization header with a webSocketFactory, the access_token query parameter without one |
await client.connect({ params: { shipmentId }, credentials: { streamToken: () => fetchStreamToken() } });
Headers, cookies and basic credentials need a webSocketFactory, as other handshake headers do.
SECURITY_SCHEMES in src/metadata.ts describes the schemes, and the servers and channels list
their scheme keys (security). Other scheme types, such as userPassword, X509 or the SASL
schemes, can’t be sent with a WebSocket handshake: they are left out with a warning.
The generated package contains src/types.ts (component schemas), src/messages.ts (payload
types and type guards), src/client.ts, src/metadata.ts (servers and channels),
src/runtime.ts and src/index.ts, with package.json and tsconfig.json.
The reply messages of an operation’s reply on the same channel are received messages like the
others. Not supported, and reported as warnings: replies on another channel or at a
runtime-expression address, WebSocket binding methods other than GET, and security schemes that
a WebSocket handshake can’t carry.
Extensions
| Extension | Effect |
|---|---|
x-apigenie.codegen.name |
on a channel: the base of its names (LobbyClient); on a message: the base of its types (PostPayload); on a component schema: the name of its type |
x-apigenie.codegen.disabled |
true on a channel or an operation leaves it out (with the operations of a channel left out) |
The extensions can live in an overlay for this target instead of in the document, e.g.
ws.overlay.yaml:
overlay: 1.0.0
info:
title: WebSocket names
version: 1.0.0
actions:
- target: $.channels.room
update:
x-apigenie:
codegen:
name: Lobby
- target: $.components.messages.ChatMessage
update:
x-apigenie:
codegen:
name: Post
apigenie-generator client ws asyncapi.yaml --overlay ws.overlay.yaml -o out
Options
-c, –config
Path to the configuration file to use. See the “Configuration” section for more information.
–overlay OVERLAY
Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those
listed under commands.generate.client_ws.overlay in the configuration file (with paths relative to
it). Warnings and errors about a value an overlay set point to the overlay. The overlays apply to
the AsyncAPI document bundled with the files it references.
–strict
Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).
–check
Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.
-o, –output
Directory where the package is generated.
–package-name
Name of the generated package. Defaults to the title of the API followed by -client.
–package-version
Version of the generated package. Defaults to the version of the API.
Configuration
version: '1.0'
commands:
generate:
client_ws:
layout: package
import_extension: .js
perspective: counterpart
| Option | Description |
|---|---|
layout |
package (default): an npm package with sources in src/; sources: the sources only |
import_extension |
Extension of relative imports: .js (default, Node.js) or an empty string (bundlers) |
perspective |
counterpart (default): the client of the described application; application: the application itself |
Verification
The codegen conformance suite runs this target on the Carpet Express AsyncAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.
This target's support tier is Tier 2. It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.
| Results | Level 1 | Level 2 | Level 3 |
|---|---|---|---|
| Release 0.12.0 | ✓ snapshots of 3.0; 32 supported, 0 not yet | ✓ pass (Version 6.0.3, ESLint 10 + typescript-eslint 8) | ✓ 3 of 3 operations pass (node) |
| Development version | ✓ snapshots of 3.0; 32 supported, 0 not yet | runs before a release | runs before a release |