@wahr/capacitor-websocket-client

Capacitor WebSocket Client Plugin.

Install

npm install @wahr/capacitor-websocket-client
npx cap sync

Platform support

• Web
• Android
• iOS

On iOS, close codes that URLSessionWebSocketTask cannot send (3000–3999, 4000–4999, and reserved codes such as 1005, 1006, and 1015) are written on the wire as 1001 (goingAway). The local onClose callback still reports the code you requested.

Example

Single connect

await WebSocket.onOpen({}, (message, err) => {
    //do something...
    console.log("onOpen event have a bug: ", err?.toString())
})

await WebSocket.onMessage({}, (message, err) => {
    //do something...
    console.log(`received message content: ${message?.data}`)
})

await WebSocket.connect({url: "ws://example.com"})

setTimeout(async () => {
    await WebSocket.send({data: "hello world!"})
}, 2000);

Multiple connect

await WebSocket.onOpen({id: "chat-websocket"}, (message, err) => {
    //do something...
    console.log("onOpen event have a bug: ", err?.toString())
})

await WebSocket.connect({url: "ws://example.com/chat", id: "chat-websocket"})

await WebSocket.onMessage({id: "notify-websocket"}, (message, err) => {
    //do something...
    console.log(`received notify content: ${message?.data}`)
})

await WebSocket.connect({url: "ws://example.com/notify", id: "notify-websocket"})

setTimeout(async () => {
    await WebSocket.send({data: "hello world!", id: "chat-websocket"})
    await WebSocket.send({data: "connect notify.", id: "notify-websocket"})
}, 2000)

API

• connect(...)
• close(...)
• send(...)
• onOpen(...)
• onMessage(...)
• onClose(...)
• onError(...)
• Interfaces
• Type Aliases

connect(...)

connect(options
:
ConnectionOptions
) =>
Promise<void>

Initiate a WebSocket connection.

Param	Type	Description
options	ConnectionOptions	The options for the connection.

Since: 0.0.1

---

close(...)

close(options ? : CloseOptions | undefined)
=>
Promise<void>

Close the connection.

Param	Type
options	CloseOptions

---

send(...)

send(options
:
SendMessageOptions
) =>
Promise<void>

Send a message.

Param	Type	Description
options	SendMessageOptions	The options for the message.

Since: 0.0.1

---

onOpen(...)

onOpen(options
:
OnOpenOptions, callback
:
OnOpenCallback
) =>
Promise<void>

Register a callback to be invoked when the connection is opened.

Param	Type	Description
options	OnOpenOptions	The options for the connection info.
callback	OnOpenCallback	The callback that will be invoked.

Since: 0.0.3

---

onMessage(...)

onMessage(options
:
OnMessageOptions, callback
:
OnMessageCallback
) =>
Promise<void>

Register a callback to be invoked when a message is received.

Param	Type	Description
options	OnMessageOptions	The options for the message info.
callback	OnMessageCallback	The callback that will be invoked.

Since: 0.0.3

---

onClose(...)

onClose(options
:
OnCloseOptions, callback
:
OnCloseCallback
) =>
Promise<void>

Register a callback to be invoked when the connection is closed.

Param	Type	Description
options	OnCloseOptions	The options for the connection info.
callback	OnCloseCallback	The callback that will be invoked.

Since: 0.0.3

---

onError(...)

onError(options
:
OnErrorOptions, callback
:
OnErrorCallback
) =>
Promise<void>

Register a callback to be invoked when an error occurs.

Param	Type	Description
options	OnErrorOptions	The options for the error info.
callback	OnErrorCallback	The callback that will be invoked.

Since: 0.0.3

---

Interfaces

ConnectionOptions

Prop	Type	Description	Since
url	string	The URL to which to connect; this should be the URL to which the WebSocket server will respond.	0.0.1
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

CloseOptions

Prop	Type	Description
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.
code	number	An integer WebSocket connection close code value indicating a reason for closure. Status code as defined by Section 7.4 of RFC 6455.
reason	string	A string explaining the reason for the connection close.

SendMessageOptions

Prop	Type	Description	Since
data	string	The data to send to the server.	0.0.1
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

OnOpenOptions

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

OnOpenData

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

OnMessageOptions

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

OnMessageData

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1
data	string	The data sent by the message emitter.	0.0.1

OnCloseOptions

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

OnCloseData

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1
code	number	An integer WebSocket connection close code value indicating a reason for closure. Status code as defined by Section 7.4 of RFC 6455.	0.0.1
reason	string	A string explaining the reason for the connection close.	0.0.1

OnErrorOptions

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1

OnErrorData

Prop	Type	Description	Since
id	string	The ID uniquely identifies a connection; no input is required, if you do not need multiple connections.	0.0.1
error	string	The error message.	0.0.1

Type Aliases

OnOpenCallback

(message: OnOpenData | null, err?: any): void

OnMessageCallback

(message: OnMessageData | null, err?: any): void

OnCloseCallback

(message: OnCloseData | null, err?: any): void

OnErrorCallback

(message: OnErrorData | null, err?: any): void