centrifuge - npm Package Compare versions

Comparing version 5.0.0-beta.1 to 5.0.0-beta.2

package.json

 {
   "name": "centrifuge",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "description": "JavaScript client SDK for bidirectional communication with Centrifugo and Centrifuge-based server from browser, NodeJS and React Native",
@@ -8,2 +8,14 @@ "main": "build/index.js",
   "module": "build/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./build/index.mjs",
+      "require": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./build/protobuf": {
+      "import": "./build/protobuf/index.mjs",
+      "require": "./build/protobuf/index.js",
+      "types": "./build/protobuf/index.d.ts"
+    }
+  },
   "files": [
@@ -17,3 +29,3 @@ "dist/**",
   "scripts": {
-    "build": "rollup -c",
+    "build": "rollup -c && ./fixup.sh",
     "prepare": "npm run build-all",
@@ -20,0 +32,0 @@ "lint": "eslint src/ --ext .js,.jsx,.ts,.tsx",

README.md

@@ -7,3 +7,3 @@ This SDK provides a client to connect to [Centrifugo](https://github.com/centrifugal/centrifugo) or any [Centrifuge-based](https://github.com/centrifugal/centrifuge) server using pure WebSocket or one of the fallback transports from web browser, ReactNative, or NodeJS environments.
 
-> **`centrifuge-js` v4.x is compatible with [Centrifugo](https://github.com/centrifugal/centrifugo) server v4 and v5 and [Centrifuge](https://github.com/centrifugal/centrifuge) >= 0.25.0. For Centrifugo v2, Centrifugo v3 and Centrifuge < 0.25.0 you should use `centrifuge-js` v2.x.**
+> **`centrifuge-js` v5.x is compatible with [Centrifugo](https://github.com/centrifugal/centrifugo) server v4 and v5 and [Centrifuge](https://github.com/centrifugal/centrifuge) >= 0.25.0. For Centrifugo v2, Centrifugo v3 and Centrifuge < 0.25.0 you should use `centrifuge-js` v2.x.**
 
@@ -45,9 +45,9 @@ * [Install](#install)
 
-In browser, you can import SDK from CDN (replace `4.0.0` with a concrete version number you want to use, see [releases](https://github.com/centrifugal/centrifuge-js/releases)):
+In browser, you can import SDK from CDN (replace `5.0.0` with a concrete version number you want to use, see [releases](https://github.com/centrifugal/centrifuge-js/releases)):
 
 ```html
-<script src="https://unpkg.com/centrifuge@4.0.0/dist/centrifuge.js"></script>
+<script src="https://unpkg.com/centrifuge@5.0.0/dist/centrifuge.js"></script>
 ```
 
-See also [centrifuge-js on cdnjs](https://cdnjs.com/libraries/centrifuge). Note that `centrifuge-js` browser builds target [ES6](https://caniuse.com/es6) at this point.
+See also [centrifuge-js on cdnjs](https://cdnjs.com/libraries/centrifuge). Note that `centrifuge-js` browser builds target [ES6](https://caniuse.com/es6).
 
@@ -147,3 +147,3 @@ **By default, library works with JSON only**, if you want to send binary payloads go to [Protobuf support](#protobuf-support) section to see how to import client with Protobuf support.
 <script src="https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js" type="text/javascript"></script>
-<script src="https://unpkg.com/centrifuge@4.0.0/dist/centrifuge.js" type="text/javascript"></script>
+<script src="https://unpkg.com/centrifuge@5.0.0/dist/centrifuge.js" type="text/javascript"></script>
 ```
@@ -249,3 +249,3 @@
 
-This is only valid for Centrifuge library and does not work for Centrifugo server at the moment. `send` method allows sending asynchronous message from a client to a server.
+This is only valid for Centrifuge server library for Go and does not work for Centrifugo server at the moment. `send` method allows sending asynchronous message from a client to a server.
 
@@ -349,2 +349,4 @@ ```javascript
 ```javascript
+import { Centrifuge, UnauthorizedError } from 'centrifuge';
+
 async function getToken() {
@@ -358,3 +360,3 @@ if (!loggedIn) {
             // Return special error to not proceed with token refreshes, client will be disconnected.
-            throw new Centrifuge.UnauthorizedError();
+            throw new UnauthorizedError();
         }
@@ -557,2 +559,4 @@ // Any other error thrown will result into token refresh re-attempts.
 ```javascript
+import { Centrifuge, UnauthorizedError } from 'centrifuge';
+
 async function getToken(ctx) {
@@ -568,3 +572,3 @@ // ctx argument has a channel.
             // Return special error to not proceed with token refreshes, subscription will be unsubscribed.
-            throw new Centrifuge.UnauthorizedError();
+            throw new UnauthorizedError();
         }
@@ -637,4 +641,48 @@ // Any other error thrown will result into token refresh re-attempts.
 
-TODO.
+We encourage using client-side subscriptions where possible as they provide a better control and isolation from connection. But in some cases you may want to use [server-side subscriptions](https://centrifugal.dev/docs/server/server_subs) (i.e. subscriptions created by server upon connection establishment).
 
+Technically, client SDK keeps server-side subscriptions in internal registry (similar to client-side subscriptions but without possibility to control them).
+
+To listen for server-side subscription events use callbacks as shown in example below:
+
+```javascript
+const client = new Centrifuge('ws://localhost:8000/connection/websocket', {});
+
+client.on('subscribed', function(ctx) {
+    // Called when subscribed to a server-side channel upon Client moving to
+    // connected state or during connection lifetime if server sends Subscribe
+    // push message.
+    console.log('subscribed to server-side channel', ctx.channel);
+});
+
+client.on('subscribing', function(ctx) {
+    // Called when existing connection lost (Client reconnects) or Client
+    // explicitly disconnected. Client continue keeping server-side subscription
+    // registry with stream position information where applicable.
+    console.log('subscribing to server-side channel', ctx.channel);
+});
+
+client.on('unsubscribed', function(ctx) {
+    // Called when server sent unsubscribe push or server-side subscription
+    // previously existed in SDK registry disappeared upon Client reconnect.
+    console.log('unsubscribed from server-side channel', ctx.channel);
+});
+
+client.on('publication', function(ctx) {
+    // Called when server sends Publication over server-side subscription.
+    console.log('publication receive from server-side channel', ctx.channel, ctx.data);
+});
+
+client.connect();
+```
+
+Server-side subscription events mostly mimic events of client-side subscriptions. But again – they do not provide control to the client and managed entirely by a server side.
+
+Additionally, Client has several top-level methods to call with server-side subscription related operations:
+
+* `publish(channel, data)`
+* `history(channel, options)`
+* `presence(channel)`
+* `presenceStats(channel)`
+
 ## Configuration options
@@ -664,6 +712,2 @@
 
-### protocol
-
-By default, client works using `json` protocol. If you want to use binary transfer with Protobuf-based protocol this option must be set to `protobuf`. See more details about Protobuf communication in a special chapter.
-
 ### token
@@ -703,6 +747,6 @@
 
-To import client with Protobuf protocol support:
+To import client which uses Protobuf protocol under the hood:
 
 ```html
-<script src="https://unpkg.com/centrifuge@4.0.0/dist/centrifuge.protobuf.js"></script>
+<script src="https://unpkg.com/centrifuge@5.0.0/dist/centrifuge.protobuf.js"></script>
 ```
@@ -713,3 +757,3 @@
 ```javascript
-import Centrifuge from 'centrifuge/build/protobuf';
+import { Centrifuge } from 'centrifuge/build/protobuf';
 ```
@@ -719,13 +763,5 @@
 
-To enable binary websocket add `protocol: 'protobuf'` option to Centrifuge configuration options:
+When running with Protobuf-based client, you can send and receive any binary data as `Uint8Array`. Make sure data is properly encoded when calling methods of Centrifuge Protobuf-based instance. For example, you can not just send JSON-like objects like in JSON protocol case, you need to encode data to `Uint8Array` first:
 
 ```javascript
-const centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket", {
-    protocol: 'protobuf'
-});
-```
-
-When running with Protobuf protocol, you can send and receive any binary data as `Uint8Array`. Make sure data is properly encoded when calling methods of Centrifuge Protobuf-based instance. For example, you can not just send JSON-like objects like in JSON protocol case, you need to encode data to `Uint8Array` first:
-
-```javascript
 const data = new TextEncoder("utf-8").encode(JSON.stringify({"any": "data"})); 
@@ -748,4 +784,4 @@ sub.publish(data);
 ```javascript
-const { Centrifuge } = require('centrifuge');
-const WebSocket = require('ws');
+import { Centrifuge } from 'centrifuge';
+import WebSocket from 'ws';
 
@@ -760,5 +796,7 @@ var centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
 ```javascript
-const { Centrifuge } = require('centrifuge');
-global.WebSocket = require('ws'); 
+import { Centrifuge } from 'centrifuge';
+import WebSocket from 'ws';
 
+global.WebSocket = WebSocket;
+
 const centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket');
@@ -765,0 +803,0 @@ ```

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

817

increased by4.88%

Worsened metrics

Total package byte prevSize

1923256

decreased by-0.95%

Number of package files

22

decreased by-15.38%

Lines of code

29976

decreased by-1.88%

Number of medium supply chain risk alerts

17

increased by6.25%

No dependency changes