client ws

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, or baseUrl), 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), subprotocols (protocols) and a webSocketFactory.
• 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 whose reply is 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 after timeoutMs (30 seconds by default) or when the connection closes. The reply also reaches its on<Message> handler. Operation requestPickup gives requestPickup, bookPickup gives requestBookPickup.
• onError, onClose, onUnknownMessage, close() and connected.

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.

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, and WebSocket binding methods other than GET. Security schemes and requirements are not generated.

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.).

-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