# webstomp-client

> Stomp client over websocket for browsers and nodejs

Latest version **1.2.6** (published 2018-11-05) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install webstomp-client
pnpm add webstomp-client
yarn add webstomp-client
bun add webstomp-client
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.6 |
| Published | 2018-11-05 |
| First published | 2016-04-01 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 95.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 298 |
| Author | Jérôme Steunou |
| Maintainers | jsteunou |
| Keywords | stomp, webstomp, websocket |

## Links

- npm: https://www.npmjs.com/package/webstomp-client
- Repository: https://github.com/JSteunou/webstomp-client
- Homepage: https://github.com/JSteunou/webstomp-client#readme
- Issues: https://github.com/JSteunou/webstomp-client/issues
- npm.io page: https://npm.io/package/webstomp-client

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.2.6 (latest) — 2018-11-05
- 1.2.5 — 2018-10-10
- 1.2.4 — 2018-07-13
- 1.2.3 — 2018-07-13
- 1.2.2 — 2018-07-03
- 1.2.1 — 2018-07-03
- 1.2.0 — 2017-10-13
- 1.1.0 — 2017-10-13
- 1.0.8 — 2017-09-18
- 1.0.7 — 2017-09-07
- 1.0.6 — 2017-02-15
- 1.0.5 — 2017-02-05
- 1.0.3 — 2016-07-31
- 1.0.2 — 2016-04-09
- 1.0.1 — 2016-04-06
- … 1 more at https://npm.io/package/webstomp-client/versions

## README

# webstomp-client

This library provides a [stomp](https://stomp.github.io/) client for Web browsers and nodejs through Web Sockets.

## Project Status

This is a fork of the original [stomp-websocket](https://github.com/jmesnil/stomp-websocket) re-written in ES6 and incorporate pending pull requests. All credits goes to the original authors: Jeff Mesnil & Jeff Lindsay.

## Browsers support

Only ES5 compatible modern browsers are supported. If you need a websocket polyfill you can use [sockjs](http://sockjs.org)

## nodejs support

As nodejs does not have a WebSocket object like browsers have, you must choose a websocket client and use [webstomp.over](https://github.com/JSteunou/webstomp-client#overws-options) instead of `webstomp.client`. Choosing a good client is maybe the most difficult part:
* [websocket](https://www.npmjs.com/package/websocket)
* [ws](https://www.npmjs.com/package/ws)
* [sockjs](https://www.npmjs.com/package/sockjs-client) If your server part is also SockJS
* ... add yours


## Example

`npm run example` will open examples in browser and try to connect to [RabbitMQ Web-Stomp](https://www.rabbitmq.com/web-stomp.html) default Web Sockets url.
`node run example/broadcast-node.js` will run a dead simple nodejs example.

## Use

`npm install webstomp-client`

### Web browser old fashion style

```html
<script type="text/javascript" src="node_modules/webstomp-client/dist/webstomp.min.js"></script>
```

`webstomp` will be a global variable.

### CommonJS

```js
var webstomp = require('webstomp-client');
```

### ES6 modules

```
import webstomp from 'webstomp-client';
```

By default it will load `dist/webstomp.js`, but the npm package.json es6 entry point to the es6 src file if you prefer loading this version.

## API

Jeff Mesnil stomp-websocket [documentation](http://jmesnil.net/stomp-websocket/doc/) is still a must read even if the API [evolved](CHANGELOG.md) a little

### webstomp

#### client(url, [options])

Uses global `WebSocket` object for you to return a webstomp `Client` object.

##### url<String>

Web Sockets endpoint url

##### options<Object>

* protocols: default to `['v10.stomp', 'v11.stomp', 'v12.stomp']`
* binary: default to `false`. See [binary](#binary) section.
* heartbeat: default to `{incoming: 10000, outgoing: 10000}`. You can provide `false` to cut it (recommended when the server is a SockJS server) or a definition object.
* debug: default to `true`. Will log frame using `console.log`

#### over(ws, [options])

Takes a `WebSocket` alike object **instance** to return a webstomp `Client` object. Allows you to use another `WebSocket` object than the default one. 2 cases for this:
* you do not want `webstomp.client` to create a default instance for you.
* you are in an old browser or nodejs and do not have a global `WebSocket` object that `webstomp.client` can use.

##### ws<WebSocket>

`WebSocket` object instance

##### options<Object>

* binary: default to `false`. See [binary](#binary) section.
* heartbeat: default to `{incoming: 10000, outgoing: 10000}`. You can provide `false` to cut it (recommended when the server is a SockJS server) or a definition object.
* debug: default to `true`. Will log frame using `console.log`

### VERSIONS

#### supportedVersions()

List all STOMP specifications supported.

#### supportedProtocols()

List all websocket STOMP protocols supported. Useful when creating your own `WebSocket` instance, although optional, protocols is often the second parameter.

### Client

A client instance can and should be created through `webstomp.client` or `webstomp.over`

#### connect

* `connect(headers, connectCallback)`
* `connect(headers, connectCallback, errorCallback)`
* `connect(login, passcode, connectCallback)`
* `connect(login, passcode, connectCallback, errorCallback)`
* `connect(login, passcode, connectCallback, errorCallback, host)`

#### disconnect(disconnectCallback, headers={})

#### send(destination, body='', headers={})

#### subscribe(destination, callback, headers={})

#### unsubscribe(id, header={})

It is preferable to unsubscribe from a subscription by calling `unsubscribe()` directly on the object returned by `client.subscribe()`

```js
var subscription = client.subscribe(destination, onmessage);
...
subscription.unsubscribe(headers);
```

`headers` are optionals

#### onreceive(frame)

If defined on the client instance this function will be called whenever a message is received and in the absence of an explicit `subscribe()`. Some brokers (at least RabbitMQ) will setup an internal routing topology for RPC patterns when a message is sent with certain headers. 

In RabbitMQ it's called [Direct Reply-To](https://www.rabbitmq.com/direct-reply-to.html)

*On the client*
```
let onreceive(frame)=>{
        console.log('Message received',frame)
}

client.onreceive=onreceive

let headers = {
        'reply-to'  :'/temp-queue/webstomp',
}

client.send('/topic/public.echo.hi.mom','a message')

```

*On the server (using [Amqplib](http://www.squaremobius.net/amqp.node/channel_api.html#channel_publish) for example)*

```
ch.publish('',raw_message.properties.replyTo,Buffer.from('a reply'))

```


#### begin([transaction])

If no transaction ID is passed, one will be created automatically

#### commit(transaction)

It is preferable to commit a transaction by calling `commit()` directly on the object returned by `client.begin()`:

```js
var tx = client.begin(txid);
...
tx.commit();
```

#### abort(transaction)

It is preferable to abort a transaction by calling `abort()` directly on the object returned by `client.begin()`:

```js
var tx = client.begin(txid);
...
tx.abort();
```

#### ack(messageID, subscription, headers={})

It is preferable to acknowledge a message by calling `ack()` directly on the message handled by a subscription callback:

```js
client.subscribe(destination, (message) => {
        // process the message
        // acknowledge it
        message.ack();
    }, {'ack': 'client'}
);
```

#### nack(messageID, subscription, headers={})

It is preferable to nack a message by calling `nack()` directly on the message handled by a subscription callback:

```js
client.subscribe(destination, (message) => {
        // process the message
        // acknowledge it
        message.nack();
    }, {'ack': 'client'}
);
```

#### debug

Will use `console.log` by default. Override it to update its behavior.


## Binary

It is possible to use binary frame instead of string frame over Web Sockets.

* client side: set the binary option to true.
* server side: use a compatible websocket server, like with [RabbitMQ Web-Stomp](https://www.rabbitmq.com/web-stomp.html) since 3.6

## Heartbeat

Not all server are compatible, you may have to deactivate this feature depending the server you are using. For example RabbitMQ Web-Stomp is compatible only since 3.6 with native Web Sockets server.

## Authors

* [Jérôme Steunou](https://github.com/JSteunou)
* [Jeff Mesnil](http://jmesnil.net/)
* [Jeff Lindsay](http://github.com/progrium)

---
_Source: https://npm.io/package/webstomp-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._