wspromisify 3.0.2 → 3.1.0

package/README.md

@@ -11,85 +11,75 @@ const responseData = await ws.send({catSaid: 'Meow!'})
 ```
 
 // If you detected some bug, want some stuff to be added, feel free to open an issue!
-Large data support (chunking), plugins and different server-side implementations are coming.
 To see a Node.js server-side part example, please, take a look on test/mock in github repo.
 
 
 Makes a Promise-like WebSocket connection.
 Features (almost all are tunable via constructor config below.)
-- Async/await ready.
-- ES-module and commonjs built-in.
+- Fully asynchronous with promises.
+- ES-module and CommonJS versions.
 - Types (d.ts) included.
-- Automatically reconnects.
+- Automatically reconnects, resends, closes when idle, pings. All parametrized.
 - Streams are supported. For example, you can stream your AI response.
+- Data piping, routing (via .route()).
+- Handy logging API.
 - Supports existent native WebSocket or ws-like implementation (ws npm package) via `socket` property.
-- And provide your own socket instance via socket config prop.
+- And provide your own socket instance via socket config fabric prop.
 - Any id and data keys to negotiate with your back-end.
 - Any (serialiser)/Decoder(deserialiser).
 - Lazy connect: connects only if something sent, then send all of them!
-- Supports middleware-adapter. E.g. you can use 'ws' package in Node!
-- Custom easy .on method with or without condition: analog to .addEventListener.
-- Can log messages/frames/response time into console or wherever you want to. (Hello, firefox 57+!)
-- Any protocols field.
-- Rejects if sent into closed socket or after some timeout without response.
-- If something sent before connection is estabilished, it sends when it's ready.
-- Pings to stay connected if necessary.
+- Supports middleware-adapter. E.g. you can use 'ws' package.
+- .on() method with or without condition: analog with .addEventListener.
+
+for more, please, take a look at its' typescript types or ask in [discussions](https://github.com/houd1ni/WebsocketPromisify/discussions).
 
 How it on Server Side ?
 ```
+Let thisnk you use default (JSON) adapter with default (id, data) props. Then:
   1. Serialized JSON is sent by this lib = {id: 'generated_id', data: your data}
-     ... or some entity from your .encode function(message_id, message_data)
   2. Some Server processing...
   3. Serialized JSON is sent back by the Server = {id: 'the same generated_id', data: feedback data}
-     ... or some entity that could be parsed by your .decode function(raw_data)
+    3.1 if it was stream, it may respond with multiple (id, data) pairs, but in the last message it must add `done: true` prop: {id, data, done: true} to let the library know that it is the last one. 
 ```
 
 
-Default constructor config is
-```javascript
-{
-  // You can also use plain text and blobs in future.
-    data_type: 'json',
-  // Debug features. Not required.
-    log: ((event, time, message) => null),
-    // Will count milliseconds for responses and put them to log function above.
-    timer: false,
-  // Set up.
-    // Required. URL to connect without a protocol.
-    // Can start with /, then current page host and port will be used.
-    url: 'localhost',
-    // Timeout after sending a message before it drops with error.
-    timeout: 1400,
-    // Reconnect timeout in seconds or null.
-    reconnect: 2,
-    // Attempts before silently givin' up.
-    reconnection_attempts: Infinity,
-    // Time in seconds after the connection is closed if nothing was sent explicitly by send().
-    max_idle_time: Infinity,
-    // Lazy connect: connects only if something sent (then sends all of them!)
-    lazy: false,
-    // Existing socket if you already have one to augment with this force.
-    socket: null,
-    // You can set your own middleware here.
-    adapter: ((host, protocols) => new WebSocket(host, protocols)),
-    // You can replace original serialisation to your own or even binary stuff. Eg MessagePack or CBOR.
-    encode: (message_id, message_data, config) => data,
-    // You can replace original deserialisation to your own or even
-    //     making the message object from binary data.
-    //     id_key and data_key could be taken from the config argument.
-    decode: (raw_message) => { message_id, message_data },
-    // WebSocket constructor's protocol field.
-    protocols: [],
-    // Unique id's and data keys to negotiate with back-end.
-    server: {
-      id_key: 'id',
-      data_key: 'data'
-    },
-    // Pings to avoid interruptions. null to disable.
-    ping: {
-      interval: 55, // seconds.
-      content: {} // goes to `data` => { id, data: {} } by default.
-    }
+Default constructor config is (all time units are in seconds):
+```typescript
+interface TimeFnParams { base: number, max: number, jitter: number }
+interface Config {
+  log: ((event, time, message): any) // only one place where time is in milliseconds.
+  timer: false // add or not time deltas to the fn above.
+  // Required if `socket` is not set. URL to connect without a protocol.
+  // Can start with /, then current page host and port will be used.
+  url: 'localhost',
+  // Timeout after sending a message before it drops with error.
+  timeout: 1.4
+  reconnect: { // Reconnect timeout in seconds or false to disable.
+    stop_after: number  // seconds before giving up.
+    on_timeout: boolean // should it reconnect on message timeout ?
+    on_break: boolean   // should it reconnect on the connection break ?
+    time_fn: (params: TimeFnParams, attempt: number): number
+    params: { base: number, max: number, jitter: number } // params for the function.
+  }
+  max_idle_time: Infinity // Time in seconds after the connection is closed if nothing was sent explicitly by send() or stream().
+  lazy: false // Lazy connect: connects only if something sent.
+  socket: null // Existing socket if you already have one to augment with wspromisify.
+  adapter: ((host, protocols): new WebSocket(host, protocols)) // your own middleware here.
+  // You can replace original serialisation to your own or even binary stuff. Eg MessagePack or CBOR.
+  encode: (message_id, message_data, config): data
+  decode: (raw_message): { message_id, message_data } // id_key and data_key could be taken from the config argument.
+  protocols: [] // WebSocket constructor's protocol field.
+  server: { // Unique id's and data keys to negotiate with back-end.
+    id_key:   'id'
+    data_key: 'data'
+    on_collision: 'error'|'pass'|'ignore' // if a message with unregistred id_key value has come. pass -> handle in 'message-ext'.
+  }
+  ping: { // Pings to avoid interruptions or false to disable.
+    interval: number       // inter-ping interval. default: 55.
+    timeout:  number       // when a server does not reply with its' `pong` in this time, close the connection. set to Infinity to disable. default: 30.
+    out: string|Uint8Array // frame content for pinging the server. default: 'ping'
+    in:  string|Uint8Array // frame content the server must send back. default: 'pong'
+  }
 }
 ```
 
@@ -102,55 +92,51 @@ Fields/Props:
 
 Methods:
 ```javascript
-
-  // Returns Promise that connection is open. Works even if it already opened.
-  ready()
-  // sends any type of message and returns a Promise.
-  send(message),
+  ready(timeout?: number) // Returns Promise that connection is open. Works even if it already opened.
+  send(message) // sends any type of message and returns a Promise.
   // Streams as async generator, resolving in chunks.
   // The server must send the same id for chunks then add done: true in the last one.
-  *stream(message),
+  *stream(message)
   // .addEventListener with optional predicate that works after reconnections.
-  on(event_name, handler, predicate = (WebSocketEvent) => true),
+  on(event_name, handler, predicate?: ((WebSocketEvent) => boolean), raw?: boolean)
+  off(event_name, handler, raw?: boolean) // `raw` is to attach it to the socket itself.
+  addEventListener(event_name, handler, {predicate, raw})    // almost alias for .on()
+  removeEventListener(event_name, handler, {predicate, raw}) // almost alias for .off()
   // Closes the connection and free up memory. Returns Promise that it has been done.
-  close()
+  close(timeout?: number)
+  // Routers or modifies frames before the library. Call next(data) to route it to the lib.
+  route(handler: (data: T, next: Function) => any)
 ```
 
 Example (more in `tests` dir in the repo):
-```javascript
+```typescript
 
-  import WSP from 'wspromisify' // or const WSP = require('wspromisify') in Node.
+  import {WebSocketClient} from 'wspromisify' // or const WSP = require('wspromisify') in Node.
 
   const somehost = 'example.com:8080'
-
-  const someFunction = async () => {
-    const ws = new WSP({
-      // If url starts with /,
-      // it results in ws(s if in https)://currentHost:currentPort/thisUrl
-      url: 'ws://example.com/ws',
-      timeout: 2e3, // 1400ms by default.
-      timer: true, // false by default.
-      // To log data trips. Events: open, close, send, reconnect, error.
-      // If timer isn't enabled, the signature is log(event, message)
-      log(event, time, message = '') {
-        if(time !== null) {
-          console.log(event, `in ${time}ms`, message)
-        } else {
-          console.log(event, message)
-        }
-      }
-    })
-
-    try {
-      // You can wait for ready by calling await ws.ready() or send it right now:
-      // the messages will be sent as soon as the connection is opened.
-      const data = await ws.send({catSaid: 'Meow!'})
-      console.log({data})
-    } catch(error) {
-      console.error('Cannot send a message due to ', error)
+  type Protocol = Uint8Array // or string (in the native WebSocket by default).
+
+  const ws = new WebSocketClient<Protocol>({
+    // if url starts with /,
+    // it results in ws(s if in https)://currentHost:currentPort/thisUrl
+    url: 'ws://example.com/ws',
+    timeout: 2,   // 2s by default.
+    timer: true,  // false by default.
+    // to log data trips. Events: open, close, send, reconnect, error.
+    // if timer isn't enabled, the signature is log(event, message)
+    log(event, time, message = '') {
+      if(time !== null) console.log(event, `in ${time}ms`, message)
+      else console.log(event, message)
     }
+  })
+
+  try {
+    // You can wait for ready by calling await ws.ready() or send it right now:
+    // the messages will be sent as soon as the connection is opened.
+    const data = await ws.send({catSaid: 'Meow!'})
+    console.log({data})
+  } catch(error) {
+    console.error('Cannot send a message due to ', error)
   }
 
-  someFunction()
-
 ```

package/dist/bundle.cjs

@@ -284,7 +284,7 @@ const default_config = () => ({
     }),
     decode: (rawMessage) => JSON.parse(rawMessage),
     protocols: [], pipes: [],
-    server: { id_key: 'id', data_key: 'data' },
+    server: { id_key: 'id', data_key: 'data', on_collision: 'error' },
     ping: { interval: 55, timeout: 30, out: 'ping', in: 'pong' }
 });
 const processConfig = (config) => {
@@ -313,6 +313,7 @@ const nil = null, inf = Infinity;
 const resolved = Promise.resolve(nil);
 const label_message = 'message';
 const label_message_ext = 'message-ext';
+const label_error = 'error';
 const zipnum = new J();
 const dnow = () => Date.now();
 const now = () => dnow() / 1e3;
@@ -334,7 +335,7 @@ const timeout_rm = (q, ff, rj, timeout = .5) => {
 };
 const genid = (q) => {
     const id = zipnum.zip((random() * (MAX_32 - 10)) | 0);
-    return id in q ? genid(q) : id;
+    return q.has(id) ? genid(q) : id;
 };
 const call_q = (q, ...args) => {
     for (const fn of q)
@@ -415,21 +416,24 @@ class WebSocketClient {
     async reconnect(attempt = 0) {
         if (this._reconnecting && attempt === 0)
             return;
+        const { reconnect } = this.config;
+        if (!reconnect)
+            throw new Error('WSC: reconnecting is disabled, but reconned h.b. called!');
         this.log('reconnect');
         this._reconnecting = true;
         this.reconnect_start = now();
         if (!isNil(this.ws))
             this.terminate();
         const { queue } = this;
-        if (attempt > 0 && isNil(await this.connect())) {
+        if (attempt > 0 && isNil(await this.connect())) { // connected.
             clear_q(call_q(queue.on_ready));
             clear_q(queue.on_ready_fail);
             this._reconnecting = false;
             this.reconnect_timeout = nil;
         }
         else {
-            const { stop_after, time_fn, params } = this.config.reconnect;
-            if (now() - this.reconnect_start > stop_after) {
+            const { stop_after, time_fn, params } = reconnect;
+            if (now() - this.reconnect_start > stop_after) { // give up.
                 this.terminate();
                 clear_q(call_q(queue.on_ready_fail));
                 clear_q(queue.on_ready);
@@ -437,7 +441,8 @@ class WebSocketClient {
                 this.reconnect_timeout = nil;
             }
             else
-                this.reconnect_timeout = sett(ms(time_fn(params, attempt)), this.reconnect.bind(this, attempt + 1));
+                this.reconnect_timeout = sett(// try more.
+                ms(time_fn(params, attempt)), this.reconnect.bind(this, attempt + 1));
         }
     }
     resetReconnect() {
@@ -448,9 +453,10 @@ class WebSocketClient {
     }
     initSocket(ws) {
         const { queue, config, router } = this;
+        const { reconnect } = config;
         this.ws = ws;
         clear_q(call_q(this.queue.on_ready));
-        const { id_key, data_key } = config.server;
+        const { id_key, data_key, on_collision } = config.server;
         // works also on previously opened sockets that do not fire 'open' event.
         this.call('open', ws);
         for (const { msg } of queue.send.values())
@@ -463,7 +469,7 @@ class WebSocketClient {
             this.ws = nil;
             clear_q(call_q(queue.on_close));
             this.call('close', ...e);
-            if (!this.intentionally_closed && config.reconnect.on_break)
+            if (!this.intentionally_closed && reconnect && reconnect.on_break)
                 this.reconnect();
         });
         const { ping } = config;
@@ -481,11 +487,22 @@ class WebSocketClient {
                         this.call(label_message, d);
                         q.ff(d);
                     }
+                    else
+                        switch (on_collision) {
+                            case 'error':
+                                const err = {
+                                    data,
+                                    message: `WSP: id_key exists in the incoming message,
+                          but does not exist in the queue!`
+                                };
+                                this.log(label_error, err);
+                                this.call(label_error, err);
+                            case 'ignore': return;
+                            case 'pass': break;
+                        }
                 }
-                else {
-                    this.log(label_message_ext, data);
-                    this.call(label_message_ext, { data });
-                }
+                this.log(label_message_ext, data);
+                this.call(label_message_ext, { data });
             }
             catch (err) {
                 console.error(err, `WSP: Decode error. Got: ${raw}`);
@@ -566,7 +583,7 @@ class WebSocketClient {
         this.ws = nil;
         this.intentionally_closed = true;
     }
-    async close(timeout = .5) {
+    close(timeout = .5) {
         return new Promise((ff, rj) => {
             if (isNull(this.ws))
                 ff(nil);
@@ -592,6 +609,7 @@ class WebSocketClient {
         this.log('send', message_data);
         const { config, queue: { send: send_q, on_ready_fail } } = this;
         const { pipes, server: { data_key } } = config;
+        const { reconnect } = config;
         const { top } = opts;
         const id = genid(send_q);
         if (isObj(top) && data_key in top)
@@ -611,12 +629,14 @@ class WebSocketClient {
         const timeout = (rj) => sett(ms(timeout_time), () => {
             if (send_q.has(id)) {
                 this.call('timeout', message_data);
-                cleanup();
-                const reject = () => rj({
-                    'Websocket timeout expired': timeout_time,
-                    'for the message': message_data
-                });
-                if (config.reconnect.on_timeout) {
+                const reject = () => {
+                    cleanup();
+                    rj({
+                        'Websocket timeout expired': timeout_time,
+                        'for the message': message_data
+                    });
+                };
+                if (reconnect && reconnect.on_timeout) {
                     on_ready_fail.push(reject);
                     this.reconnect();
                 }

package/dist/bundle.d.ts

@@ -43,7 +43,7 @@ declare namespace wsc {
 				max: number;
 				jitter: number;
 			};
-		};
+		} | false;
 		max_idle_time: number;
 		lazy: boolean;
 		socket: Socket | null;
@@ -57,6 +57,7 @@ declare namespace wsc {
 		server: {
 			id_key: string;
 			data_key: string;
+			on_collision: "error" | "pass" | "ignore";
 		};
 		ping: {
 			interval: number;

package/dist/bundle.mjs

@@ -282,7 +282,7 @@ const default_config = () => ({
     }),
     decode: (rawMessage) => JSON.parse(rawMessage),
     protocols: [], pipes: [],
-    server: { id_key: 'id', data_key: 'data' },
+    server: { id_key: 'id', data_key: 'data', on_collision: 'error' },
     ping: { interval: 55, timeout: 30, out: 'ping', in: 'pong' }
 });
 const processConfig = (config) => {
@@ -311,6 +311,7 @@ const nil = null, inf = Infinity;
 const resolved = Promise.resolve(nil);
 const label_message = 'message';
 const label_message_ext = 'message-ext';
+const label_error = 'error';
 const zipnum = new J();
 const dnow = () => Date.now();
 const now = () => dnow() / 1e3;
@@ -332,7 +333,7 @@ const timeout_rm = (q, ff, rj, timeout = .5) => {
 };
 const genid = (q) => {
     const id = zipnum.zip((random() * (MAX_32 - 10)) | 0);
-    return id in q ? genid(q) : id;
+    return q.has(id) ? genid(q) : id;
 };
 const call_q = (q, ...args) => {
     for (const fn of q)
@@ -413,21 +414,24 @@ class WebSocketClient {
     async reconnect(attempt = 0) {
         if (this._reconnecting && attempt === 0)
             return;
+        const { reconnect } = this.config;
+        if (!reconnect)
+            throw new Error('WSC: reconnecting is disabled, but reconned h.b. called!');
         this.log('reconnect');
         this._reconnecting = true;
         this.reconnect_start = now();
         if (!isNil(this.ws))
             this.terminate();
         const { queue } = this;
-        if (attempt > 0 && isNil(await this.connect())) {
+        if (attempt > 0 && isNil(await this.connect())) { // connected.
             clear_q(call_q(queue.on_ready));
             clear_q(queue.on_ready_fail);
             this._reconnecting = false;
             this.reconnect_timeout = nil;
         }
         else {
-            const { stop_after, time_fn, params } = this.config.reconnect;
-            if (now() - this.reconnect_start > stop_after) {
+            const { stop_after, time_fn, params } = reconnect;
+            if (now() - this.reconnect_start > stop_after) { // give up.
                 this.terminate();
                 clear_q(call_q(queue.on_ready_fail));
                 clear_q(queue.on_ready);
@@ -435,7 +439,8 @@ class WebSocketClient {
                 this.reconnect_timeout = nil;
             }
             else
-                this.reconnect_timeout = sett(ms(time_fn(params, attempt)), this.reconnect.bind(this, attempt + 1));
+                this.reconnect_timeout = sett(// try more.
+                ms(time_fn(params, attempt)), this.reconnect.bind(this, attempt + 1));
         }
     }
     resetReconnect() {
@@ -446,9 +451,10 @@ class WebSocketClient {
     }
     initSocket(ws) {
         const { queue, config, router } = this;
+        const { reconnect } = config;
         this.ws = ws;
         clear_q(call_q(this.queue.on_ready));
-        const { id_key, data_key } = config.server;
+        const { id_key, data_key, on_collision } = config.server;
         // works also on previously opened sockets that do not fire 'open' event.
         this.call('open', ws);
         for (const { msg } of queue.send.values())
@@ -461,7 +467,7 @@ class WebSocketClient {
             this.ws = nil;
             clear_q(call_q(queue.on_close));
             this.call('close', ...e);
-            if (!this.intentionally_closed && config.reconnect.on_break)
+            if (!this.intentionally_closed && reconnect && reconnect.on_break)
                 this.reconnect();
         });
         const { ping } = config;
@@ -479,11 +485,22 @@ class WebSocketClient {
                         this.call(label_message, d);
                         q.ff(d);
                     }
+                    else
+                        switch (on_collision) {
+                            case 'error':
+                                const err = {
+                                    data,
+                                    message: `WSP: id_key exists in the incoming message,
+                          but does not exist in the queue!`
+                                };
+                                this.log(label_error, err);
+                                this.call(label_error, err);
+                            case 'ignore': return;
+                            case 'pass': break;
+                        }
                 }
-                else {
-                    this.log(label_message_ext, data);
-                    this.call(label_message_ext, { data });
-                }
+                this.log(label_message_ext, data);
+                this.call(label_message_ext, { data });
             }
             catch (err) {
                 console.error(err, `WSP: Decode error. Got: ${raw}`);
@@ -564,7 +581,7 @@ class WebSocketClient {
         this.ws = nil;
         this.intentionally_closed = true;
     }
-    async close(timeout = .5) {
+    close(timeout = .5) {
         return new Promise((ff, rj) => {
             if (isNull(this.ws))
                 ff(nil);
@@ -590,6 +607,7 @@ class WebSocketClient {
         this.log('send', message_data);
         const { config, queue: { send: send_q, on_ready_fail } } = this;
         const { pipes, server: { data_key } } = config;
+        const { reconnect } = config;
         const { top } = opts;
         const id = genid(send_q);
         if (isObj(top) && data_key in top)
@@ -609,12 +627,14 @@ class WebSocketClient {
         const timeout = (rj) => sett(ms(timeout_time), () => {
             if (send_q.has(id)) {
                 this.call('timeout', message_data);
-                cleanup();
-                const reject = () => rj({
-                    'Websocket timeout expired': timeout_time,
-                    'for the message': message_data
-                });
-                if (config.reconnect.on_timeout) {
+                const reject = () => {
+                    cleanup();
+                    rj({
+                        'Websocket timeout expired': timeout_time,
+                        'for the message': message_data
+                    });
+                };
+                if (reconnect && reconnect.on_timeout) {
                     on_ready_fail.push(reject);
                     this.reconnect();
                 }

package/package.json

@@ -30,18 +30,7 @@
     "type": "git",
     "url": "git+https://github.com/houd1ni/WebsocketPromisify.git"
   },
-  "scripts": {
-    "lint": "tslint src/*.ts",
-    "test": "tsx test/index",
-    "test:report": "nyc npm test && nyc report --reporter=text-lcov > coverage.lcov && codecov",
-    "gentypes": "dts-bundle-generator --no-check -o dist/bundle.d.ts src/WSC.ts",
-    "dev": "cross-env NODE_ENV=development BUILD=es rollup -c",
-    "prod:cjs": "cross-env NODE_ENV=production BUILD=cjs rollup -c",
-    "prod:es": "cross-env NODE_ENV=production BUILD=es rollup -c",
-    "prod": "npm run gentypes && npm run prod:es && npm run prod:cjs",
-    "all": "npm run dev && npm run prod"
-  },
-  "version": "3.0.2",
+  "version": "3.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -75,5 +64,16 @@
   "dependencies": {
     "pepka": "^1.13.0",
     "zipnum": "^2.1.3"
+  },
+  "scripts": {
+    "lint": "tslint src/*.ts",
+    "test": "tsx test/index",
+    "test:report": "nyc npm test && nyc report --reporter=text-lcov > coverage.lcov && codecov",
+    "gentypes": "dts-bundle-generator --no-check -o dist/bundle.d.ts src/WSC.ts",
+    "dev": "cross-env NODE_ENV=development BUILD=es rollup -c",
+    "prod:cjs": "cross-env NODE_ENV=production BUILD=cjs rollup -c",
+    "prod:es": "cross-env NODE_ENV=production BUILD=es rollup -c",
+    "prod": "npm run gentypes && npm run prod:es && npm run prod:cjs",
+    "all": "npm run dev && npm run prod"
   }
-}
+}