@polytric/openws-sdkgen 0.0.12 → 0.0.14

package/README.md

@@ -41,7 +41,7 @@ The CLI exposes the following options:
 - `--out` (string): Output directory for generated code.
 - `--project` (string): Project/namespace prefix for generated code.
 - `--network` (string): Network name to generate.
-- `--hostRole` (string): Participant role name that represents the host side.
+- `--hostRole` (string): Peer role name that represents the host side.
 - `--language` (string): Target language (`csharp`, `javascript`, or `typescript`).
 - `--environment` (string|array): Target environment (`unity`, `node`, `browser`).
 

package/dist/main.cjs

@@ -457,7 +457,7 @@ function parseInput(ctx) {
   }).option("hostRole", {
     type: "array",
     string: true,
-    description: "The target participant roles that use the generated code",
+    description: "The target peer roles that use the generated code",
     demandOption: true
   }).option("language", {
     type: "string",

package/dist/main.js

@@ -434,7 +434,7 @@ function parseInput(ctx) {
   }).option("hostRole", {
     type: "array",
     string: true,
-    description: "The target participant roles that use the generated code",
+    description: "The target peer roles that use the generated code",
     demandOption: true
   }).option("language", {
     type: "string",

package/dist/plans/typescript.cjs

@@ -216,7 +216,7 @@ function createPlan(ctx) {
       const remoteRoles = getPeerRoles(networkSpec, rolesByName, hostRole.roleName).map(
         (remoteRole) => ({
           ...remoteRole,
-          scopedApiName: `${hostRole.className}${remoteRole.className}Api`,
+          scopedPeerName: `${hostRole.className}${remoteRole.className}Peer`,
           allowedMethodNames: getAllowedMessageMethodNames(
             networkSpec,
             remoteRole.roleName,
@@ -342,9 +342,9 @@ function toRoleInfo(role) {
     className,
     roleClassName: className,
     hostRoleClassName: `${className}Host`,
-    apiName: `${className}Api`,
+    peerName: `${className}Peer`,
     varName: camelCase(role.name),
-    apiVarName: `${camelCase(role.name)}Api`,
+    peerVarName: `${camelCase(role.name)}Peer`,
     fileName,
     roleFileName: `${fileName}-role`,
     description: role.description || "",

package/dist/plans/typescript.js

@@ -176,7 +176,7 @@ function createPlan(ctx) {
       const remoteRoles = getPeerRoles(networkSpec, rolesByName, hostRole.roleName).map(
         (remoteRole) => ({
           ...remoteRole,
-          scopedApiName: `${hostRole.className}${remoteRole.className}Api`,
+          scopedPeerName: `${hostRole.className}${remoteRole.className}Peer`,
           allowedMethodNames: getAllowedMessageMethodNames(
             networkSpec,
             remoteRole.roleName,
@@ -302,9 +302,9 @@ function toRoleInfo(role) {
     className,
     roleClassName: className,
     hostRoleClassName: `${className}Host`,
-    apiName: `${className}Api`,
+    peerName: `${className}Peer`,
     varName: camelCase(role.name),
-    apiVarName: `${camelCase(role.name)}Api`,
+    peerVarName: `${camelCase(role.name)}Peer`,
     fileName,
     roleFileName: `${fileName}-role`,
     description: role.description || "",

package/dist/templates/typescript/package.json.ejs

@@ -23,7 +23,7 @@
     },
     "files": ["dist"],
     "dependencies": {
-        "@polytric/openws": "^0.0.6"
+        "@polytric/openws": "^0.0.7"
     },
     "scripts": {
         "build": "tsup",

package/dist/templates/typescript/src/network.ts.ejs

@@ -9,12 +9,18 @@ export const endpoints = <%- JSON.stringify(
 ) %>
 
 <% if (ctx.isTypeScript) { -%>
+/**
+ * Wire-format message envelope used by this OpenWS SDK.
+ */
 export interface OpenWsEnvelope<Payload = unknown> {
     fromRole: string
     messageName: string
     payload: Payload
 }
 
+/**
+ * Connection endpoint metadata from the OpenWS spec.
+ */
 export interface OpenWsEndpoint {
     scheme: string
     host?: string
@@ -23,9 +29,15 @@ export interface OpenWsEndpoint {
 }
 
 export type Unsubscribe = () => void
-export type TransportEvent = 'message' | 'error'
+export type TransportEvent = 'message' | 'error' | 'close'
 export type TransportHandler = (data: unknown) => void | Promise<void>
 
+/**
+ * Minimal transport contract used by generated SDK clients.
+ *
+ * Implement this interface to plug in a custom socket, browser WebSocket,
+ * server-side WebSocket client, or test transport.
+ */
 export interface Transport {
     send(data: string): void | Promise<void>
     on?(event: TransportEvent, handler: TransportHandler): unknown
@@ -38,24 +50,47 @@ export interface BindTransportOptions {
     closeOnError?: boolean
 }
 
+/**
+ * Callback surface used by `bindTransport`.
+ *
+ * `handle...` methods are framework entrypoints called by transport glue.
+ * Generated clients expose matching `on...` methods for application callbacks.
+ */
 export interface RawMessageHandler {
     handleRawMessage(data: string): void | Promise<void>
-    messageError?(error: unknown): void | Promise<void>
-    socketError?(error: unknown): void | Promise<void>
+    handleMessageError?(error: unknown): void | Promise<void>
+    handleSocketError?(error: unknown): void | Promise<void>
+    handleSocketClose?(event: unknown): void | Promise<void>
 }
 
+/**
+ * Encodes an OpenWS envelope for transport.
+ */
 export function encodeEnvelope(envelope: OpenWsEnvelope): string {
     return JSON.stringify(envelope)
 }
 
+/**
+ * Decodes raw transport data into an OpenWS envelope.
+ */
 export function decodeEnvelope(data: string): OpenWsEnvelope {
     return JSON.parse(data) as OpenWsEnvelope
 }
 
+/**
+ * Returns true when a transport can be bound to generated client callbacks.
+ */
 export function canBindTransport(transport: Transport): boolean {
     return typeof transport.on === 'function'
 }
 
+/**
+ * Binds transport events to a generated client or compatible raw message handler.
+ *
+ * Transport `message` events call `handleRawMessage`, message handling failures
+ * call `handleMessageError`, transport `error` events call `handleSocketError`,
+ * and transport `close` events call `handleSocketClose`.
+ */
 export function bindTransport(
     transport: Transport,
     handler: RawMessageHandler,
@@ -65,14 +100,17 @@ export function bindTransport(
         try {
             await handler.handleRawMessage(await normalizeMessageData(data))
         } catch (error) {
-            await handler.messageError?.(error)
+            await handler.handleMessageError?.(error)
             if (options.closeOnError) {
                 transport.close?.()
             }
         }
     }
     const handleSocketError = async (error: unknown) => {
-        await handler.socketError?.(error)
+        await handler.handleSocketError?.(error)
+    }
+    const handleSocketClose = async (event: unknown) => {
+        await handler.handleSocketClose?.(event)
     }
 
     const nodeHandler = (data: unknown, ..._args: unknown[]) => {
@@ -81,6 +119,9 @@ export function bindTransport(
     const nodeErrorHandler = (error: unknown, ..._args: unknown[]) => {
         void handleSocketError(error)
     }
+    const nodeCloseHandler = (event: unknown, ..._args: unknown[]) => {
+        void handleSocketClose(event)
+    }
 
     if (typeof transport.on !== 'function') {
         throw new Error('Transport must support on("message")')
@@ -88,12 +129,17 @@ export function bindTransport(
 
     const messageUnsubscribe = transport.on('message', nodeHandler)
     const errorUnsubscribe = transport.on('error', nodeErrorHandler)
+    const closeUnsubscribe = transport.on('close', nodeCloseHandler)
     return () => {
         if (typeof messageUnsubscribe === 'function') messageUnsubscribe()
         if (typeof errorUnsubscribe === 'function') errorUnsubscribe()
+        if (typeof closeUnsubscribe === 'function') closeUnsubscribe()
     }
 }
 
+/**
+ * WebSocket-backed transport implementation for generated SDK clients.
+ */
 export class WsTransport implements Transport {
     private socket?: unknown
     private socketUnsubscribe?: Unsubscribe
@@ -101,6 +147,7 @@ export class WsTransport implements Transport {
     private readonly listeners: Record<TransportEvent, Set<TransportHandler>> = {
         message: new Set(),
         error: new Set(),
+        close: new Set(),
     }
 
     constructor(socket?: unknown) {
@@ -109,6 +156,9 @@ export class WsTransport implements Transport {
         }
     }
 
+    /**
+     * Opens the underlying WebSocket when needed and waits until it is ready.
+     */
     async connect(_roleName: string, endpoint?: OpenWsEndpoint): Promise<void> {
         if (!this.socket) {
             if (!endpoint) {
@@ -119,10 +169,16 @@ export class WsTransport implements Transport {
         await this.waitForOpen()
     }
 
+    /**
+     * Closes the underlying WebSocket connection.
+     */
     async disconnect(): Promise<void> {
         this.close()
     }
 
+    /**
+     * Sends already-encoded OpenWS envelope data.
+     */
     async send(data: string): Promise<void> {
         await this.waitForOpen()
         const socket = this.requireSocket() as { send?: (data: string) => void | Promise<void> }
@@ -132,6 +188,9 @@ export class WsTransport implements Transport {
         await socket.send(data)
     }
 
+    /**
+     * Registers a transport event callback.
+     */
     on(event: TransportEvent, handler: TransportHandler): Unsubscribe {
         this.listeners[event].add(handler)
         return () => {
@@ -139,17 +198,17 @@ export class WsTransport implements Transport {
         }
     }
 
+    /**
+     * Closes and clears the current socket.
+     */
     close(): void {
         const socket = this.socket as { close?: () => void } | undefined
         socket?.close?.()
-        this.socketUnsubscribe?.()
-        this.socket = undefined
-        this.socketUnsubscribe = undefined
-        this.openPromise = undefined
+        this.clearSocket()
     }
 
     private bindSocket(socket: unknown): void {
-        this.socketUnsubscribe?.()
+        this.clearSocket()
         this.socket = socket
         this.openPromise = undefined
 
@@ -159,12 +218,31 @@ export class WsTransport implements Transport {
         const unsubscribeError = addSocketListener(socket, 'error', error => {
             void this.emit('error', error)
         })
+        const unsubscribeClose = addSocketListener(socket, 'close', event => {
+            void this.handleSocketClose(socket, event)
+        })
         this.socketUnsubscribe = () => {
             unsubscribeMessage()
             unsubscribeError()
+            unsubscribeClose()
         }
     }
 
+    private async handleSocketClose(socket: unknown, event: unknown): Promise<void> {
+        if (this.socket !== socket) {
+            return
+        }
+        this.clearSocket()
+        await this.emit('close', event)
+    }
+
+    private clearSocket(): void {
+        this.socketUnsubscribe?.()
+        this.socket = undefined
+        this.socketUnsubscribe = undefined
+        this.openPromise = undefined
+    }
+
     private async emit(event: TransportEvent, data: unknown): Promise<void> {
         for (const handler of this.listeners[event]) {
             await handler(data)
@@ -196,9 +274,14 @@ export class WsTransport implements Transport {
                 cleanup()
                 reject(error)
             })
+            const unsubscribeClose = addSocketListener(socket, 'close', event => {
+                cleanup()
+                reject(event instanceof Error ? event : new Error('WebSocket closed before opening'))
+            })
             cleanup = () => {
                 unsubscribeOpen()
                 unsubscribeError()
+                unsubscribeClose()
             }
         })
         await this.openPromise
@@ -243,7 +326,7 @@ function getReadyState(socket: unknown): number | undefined {
 
 function addSocketListener(
     socket: unknown,
-    event: 'open' | 'message' | 'error',
+    event: 'open' | 'message' | 'error' | 'close',
     handler: (...args: unknown[]) => void
 ): Unsubscribe {
     const target = socket as {
@@ -289,31 +372,50 @@ function addSocketListener(
     }
 }
 <% } else { -%>
+/**
+ * Encodes an OpenWS envelope for transport.
+ */
 export function encodeEnvelope(envelope) {
     return JSON.stringify(envelope)
 }
 
+/**
+ * Decodes raw transport data into an OpenWS envelope.
+ */
 export function decodeEnvelope(data) {
     return JSON.parse(data)
 }
 
+/**
+ * Returns true when a transport can be bound to generated client callbacks.
+ */
 export function canBindTransport(transport) {
     return typeof transport.on === 'function'
 }
 
+/**
+ * Binds transport events to a generated client or compatible raw message handler.
+ *
+ * Transport `message` events call `handleRawMessage`, message handling failures
+ * call `handleMessageError`, transport `error` events call `handleSocketError`,
+ * and transport `close` events call `handleSocketClose`.
+ */
 export function bindTransport(transport, handler, options = {}) {
     const handleData = async data => {
         try {
             await handler.handleRawMessage(await normalizeMessageData(data))
         } catch (error) {
-            await handler.messageError?.(error)
+            await handler.handleMessageError?.(error)
             if (options.closeOnError) {
                 transport.close?.()
             }
         }
     }
     const handleSocketError = async error => {
-        await handler.socketError?.(error)
+        await handler.handleSocketError?.(error)
+    }
+    const handleSocketClose = async event => {
+        await handler.handleSocketClose?.(event)
     }
 
     const nodeHandler = data => {
@@ -322,6 +424,9 @@ export function bindTransport(transport, handler, options = {}) {
     const nodeErrorHandler = error => {
         void handleSocketError(error)
     }
+    const nodeCloseHandler = event => {
+        void handleSocketClose(event)
+    }
 
     if (typeof transport.on !== 'function') {
         throw new Error('Transport must support on("message")')
@@ -329,12 +434,17 @@ export function bindTransport(transport, handler, options = {}) {
 
     const messageUnsubscribe = transport.on('message', nodeHandler)
     const errorUnsubscribe = transport.on('error', nodeErrorHandler)
+    const closeUnsubscribe = transport.on('close', nodeCloseHandler)
     return () => {
         if (typeof messageUnsubscribe === 'function') messageUnsubscribe()
         if (typeof errorUnsubscribe === 'function') errorUnsubscribe()
+        if (typeof closeUnsubscribe === 'function') closeUnsubscribe()
     }
 }
 
+/**
+ * WebSocket-backed transport implementation for generated SDK clients.
+ */
 export class WsTransport {
     socket
     socketUnsubscribe
@@ -342,6 +452,7 @@ export class WsTransport {
     listeners = {
         message: new Set(),
         error: new Set(),
+        close: new Set(),
     }
 
     constructor(socket) {
@@ -350,6 +461,9 @@ export class WsTransport {
         }
     }
 
+    /**
+     * Opens the underlying WebSocket when needed and waits until it is ready.
+     */
     async connect(_roleName, endpoint) {
         if (!this.socket) {
             if (!endpoint) {
@@ -360,10 +474,16 @@ export class WsTransport {
         await this.waitForOpen()
     }
 
+    /**
+     * Closes the underlying WebSocket connection.
+     */
     async disconnect() {
         this.close()
     }
 
+    /**
+     * Sends already-encoded OpenWS envelope data.
+     */
     async send(data) {
         await this.waitForOpen()
         const socket = this.requireSocket()
@@ -373,6 +493,9 @@ export class WsTransport {
         await socket.send(data)
     }
 
+    /**
+     * Registers a transport event callback.
+     */
     on(event, handler) {
         this.listeners[event].add(handler)
         return () => {
@@ -380,16 +503,16 @@ export class WsTransport {
         }
     }
 
+    /**
+     * Closes and clears the current socket.
+     */
     close() {
         this.socket?.close?.()
-        this.socketUnsubscribe?.()
-        this.socket = undefined
-        this.socketUnsubscribe = undefined
-        this.openPromise = undefined
+        this.clearSocket()
     }
 
     bindSocket(socket) {
-        this.socketUnsubscribe?.()
+        this.clearSocket()
         this.socket = socket
         this.openPromise = undefined
 
@@ -399,12 +522,31 @@ export class WsTransport {
         const unsubscribeError = addSocketListener(socket, 'error', error => {
             void this.emit('error', error)
         })
+        const unsubscribeClose = addSocketListener(socket, 'close', event => {
+            void this.handleSocketClose(socket, event)
+        })
         this.socketUnsubscribe = () => {
             unsubscribeMessage()
             unsubscribeError()
+            unsubscribeClose()
         }
     }
 
+    async handleSocketClose(socket, event) {
+        if (this.socket !== socket) {
+            return
+        }
+        this.clearSocket()
+        await this.emit('close', event)
+    }
+
+    clearSocket() {
+        this.socketUnsubscribe?.()
+        this.socket = undefined
+        this.socketUnsubscribe = undefined
+        this.openPromise = undefined
+    }
+
     async emit(event, data) {
         for (const handler of this.listeners[event]) {
             await handler(data)
@@ -436,9 +578,14 @@ export class WsTransport {
                 cleanup()
                 reject(error)
             })
+            const unsubscribeClose = addSocketListener(socket, 'close', event => {
+                cleanup()
+                reject(event instanceof Error ? event : new Error('WebSocket closed before opening'))
+            })
             cleanup = () => {
                 unsubscribeOpen()
                 unsubscribeError()
+                unsubscribeClose()
             }
         })
         await this.openPromise

package/dist/templates/typescript/src/roles/role.ts.ejs

@@ -10,7 +10,7 @@ import type { <%= payloadImports.join(', ') %> } from '<%= modelImportPath %>'
 import { <%= peerRoleImports.join(', ') %> } from './index'
 <% } -%>
 
-export interface <%= ctx.apiName %> {
+export interface <%= ctx.peerName %> {
 <% for (const message of ctx.messages) { -%>
     <%= message.methodName %>(payload: <%= message.payloadType %> | <%= message.payloadType %>Init): Promise<void>
 <% } -%>