Installation

npm install @lunafw/core @lunafw/common @lunafw/platform-ws reflect-metadata ws

Usage

import { LunaFactory } from '@lunafw/common'
import { WsAdapter } from '@lunafw/platform-ws'

import { AppModule } from './app.module'

const bootstrap = async (): Promise<void> => {
  const app = await LunaFactory.createApplication(
    AppModule,
    new WsAdapter({ port: 3001 }),
  )
  await app.start()
}
bootstrap()

Multi-adapter (HTTP + WebSocket)

import { LunaFactory } from '@lunafw/common'
import { ExpressAdapter } from '@lunafw/platform-express'
import { WsAdapter } from '@lunafw/platform-ws'

const app = await LunaFactory.createApplication(AppModule, [
  new ExpressAdapter({ port: 3000 }),
  new WsAdapter({ port: 3001 }),
])
await app.start()

Message format

Clients send JSON messages with an event field and an optional data field:

{ "event": "chat.send", "data": { "text": "Hello!" } }

The adapter routes the message to the handler registered for that event and sends the handler's return value back as JSON.

Controllers

Use the same @Controller and @On decorators. The route key is built as <prefix>.<event> (or just <event> when prefix is empty).

import { Injectable } from '@lunafw/core'
import { Controller, LunaMessage, On } from '@lunafw/common'

@Injectable()
@Controller('chat')
export class ChatController {
  // listens for event "chat.send"
  @On('send', '/')
  handleMessage(message: LunaMessage) {
    const { text } = message.payload as { text: string }
    return { echo: text }
  }
}

Client side:

import WebSocket from 'ws'

const ws = new WebSocket('ws://localhost:3001')
ws.send(JSON.stringify({ event: 'chat.send', data: { text: 'Hello!' } }))
ws.on('message', (data) => console.log(JSON.parse(data.toString())))
// → { echo: 'Hello!' }

LunaMessage for WebSocket

{
  context: 'ws',
  payload: data,             // the `data` field from the incoming JSON
  metadata: {
    event: 'chat.send',     // full event string
    socketId: '<string>',   // unique ID per connection
  }
}

Guards, Pipes, Interceptors, Filters

All middleware from @lunafw/common works identically over WebSocket — the same @UseGuards, @UsePipes, @UseInterceptors, @UseFilters decorators apply.

API

new WsAdapter(options)

| Option | Type | Description | |--------|------|-------------| | port | number | Port to listen on. Pass 0 to let the OS assign a free port. |

adapter.getPort(): number

Returns the TCP port the server is bound to. Useful when port: 0 was passed.

License

MIT