# ws

## Description

Creates a [socket.io websocket client](https://github.com/socketio/socket.io-client/blob/master/docs/API.md) wrapped in an Observable. The Observable is a vanilla RxJS Observable which emits actions and exposes its API using \[rxws operators]\((<https://brianbuccaneer.gitbook.io/rxws/api/operators>).

## Usage

```javascript
import { share } from 'rxjs/operators';
import { ws, messages } from '@buccaneer/rxws';

// create a websocket
const websocketParams = {
  url: 'wss://mysite.com',
  topics: ['message', 'news'],
};
const ws$ = ws(websocketParams).pipe(
  share() // create the websocket and multicast it into an RxJS Subject
);

// get messages from the websocket:
const message$ = ws.pipe(
  messages()
);

message$.subscribe(console.log);
// This would log the messages received from the server
```

## API

```
ws({
  url,
  topics=['message'],
  socketOptions={transports: ['websocket']}
})
```

### Since

1.0

### Parameters

* `url<String>`: The URL of the Websocket server

### Options

* `topics[<String>]`: An array of the topics to which the WebSocket client should subscribe. Defaults to `['message']`.
* `socketOptions`: An object containing [socket.io client options](https://socket.io/docs/client-api/).

### Returns

`Observable`. An RxJS Observable. This contains a stream of events. The websocket is intended to be used with rxws operators.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://brianbuccaneer.gitbook.io/rxws/dev-1/api/creators/ws.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.