pm_socket.js

Quickstart

Load the script, configure callbacks, then connect. The matching Python PmSocket server adapter sends the required ::connect:: handshake automatically.

<script src="https://update.pmblue.us/resources/pm_socket/js"></script>
<script>
  const socket = new WebSocketConnection("wss://example.com/events");

  socket.connect_handler = () => {
    console.log("WebSocket transport is open");
  };

  socket.handler = (message) => {
    console.log("Received:", message);
  };

  socket.connect();
</script>

Installation

<script src="https://update.pmblue.us/resources/pm_socket/js"></script>

<script src="/static/resources/pm_socket.js"></script>

The script defines WebSocketConnection in the global scope. It is not currently packaged as an ES module or npm package.

Connection lifecycle

1. connect() creates the native WebSocket and attaches its event handlers.
2. When the browser fires open, connect_handler() runs. At this point the transport is open, but alive may still be false.
3. The compatible server sends ::connect::. The client consumes it and sets alive = true.
4. Application messages are passed to handler(message) and any active waitFor() listener.
5. On an unexpected close after the handshake, the client tries to reconnect.
6. disconnect() marks the connection inactive, closes it, and prevents reconnect handling for that close.

Sending and receiving messages

Receive application messages

Assign one global handler before calling connect(). It receives event.data, not the browser MessageEvent.

socket.handler = (message) => {
  const payload = JSON.parse(message);
  console.log(payload.type, payload.data);
};

Send safely

sendData(data) sends only while the socket is open; otherwise it logs an error. Prefer it for normal application traffic. Like the native WebSocket API, objects must be serialized first.

socket.sendData(JSON.stringify({
  type: "subscribe",
  channel: "orders"
}));

send(data) forwards directly to socket.send(data) without checking state. Use it only when you have already confirmed isConnected().

Match a one-time response

waitFor(condition, callback, timeout) adds a temporary message listener. The first message for which condition(message) returns true is passed to the callback, then the listener removes itself.

const requestId = crypto.randomUUID();

socket.waitFor(
  (raw) => {
    try {
      return JSON.parse(raw).requestId === requestId;
    } catch {
      return false;
    }
  },
  (raw) => console.log("Matched response:", JSON.parse(raw)),
  5000
);

socket.sendData(JSON.stringify({ type: "lookup", requestId }));

Latency and keepalive

Measure round-trip latency

ping() sends ::ping::, waits for ::pong::, and resolves with round-trip latency in milliseconds.

if (socket.isConnected()) {
  const milliseconds = await socket.ping();
  console.log(`Latency: ${milliseconds} ms`);
}

Enable automatic pinging

Set auto_ping_interval to a number of seconds before connecting. Each interval runs ping(); if the matching ping has not completed after two seconds, the socket is closed.

const socket = new WebSocketConnection("wss://example.com/events");
socket.auto_ping_interval = 30; // seconds; set before connect()
socket.connect();

Reserved protocol messages

This page follows resources/pm_socket.js, the file served by /resources/pm_socket/js. The alternate pm_socket_ and pm_socket_v1 filenames are separate resources; they are not selected by this URL. The served file has no version declaration.

These exact strings are used internally. The client consumes ::connect::, ::disconnect::, and ::ping:: before its application handler; ::pong:: also completes active ping listeners and can still reach handler or waitFor(). Do not use any of them as application payloads.

These are text-frame application messages, separate from native WebSocket ping and pong control frames.

API reference

Creates a disconnected client. url must be a WebSocket URL accepted by the browser, normally wss://….

Creates a native socket, installs open/close/error/message handlers, and starts the connection. Configure callbacks and options first. Calling it more than once can create multiple live sockets; do not call it again while connected.

If a socket exists, sends ::disconnect:: when alive is true, closes the transport, clears socket, and sets alive to false. Safe to call when no socket exists.

Returns a truthy value only when a socket exists and its native state is WebSocket.OPEN. Because the implementation uses this.socket && …, it returns null before a socket exists rather than the literal boolean false.

Sends a string, Blob, ArrayBuffer, or typed-array view when connected. Logs WebSocket is not connected. when closed.

Calls the native socket's send() directly, with no existence or state guard. Native errors can propagate.

When connected, resolves with latency in milliseconds after receiving ::pong::. When disconnected, logs an error and resolves to undefined. The current method has no timeout, so a missing pong leaves its Promise pending.

Adds a one-time matching listener. condition receives message data and must return a truthy value to call callback(message). A positive timeout removes the listener silently. A timeout of 0 leaves it active until a match.

Properties and configuration

Wrapper and native WebSocket objects

new WebSocketConnection(url) creates application state only. After connect(), its socket property holds the browser's native WebSocket. A reconnect replaces that native object; listeners and properties attached directly to the previous socket are not transferred automatically.

Keep business state in your application rather than the legacy waiting dictionary. Use connect_handler to reapply native socket settings after each reconnect. The Python partner receives native messages through PmSocket objects.

Browser workflows

1. Wrap a matched response in a Promise with a deadline

The Python state-server example echoes request_id. This helper supplies the Promise and timeout rejection that waitFor() itself does not provide. A connection loss will eventually reject at the deadline.

const scheme = location.protocol === 'https:' ? 'wss' : 'ws';
const stateSocket = new WebSocketConnection(`${scheme}://${location.host}/state/ws`);
let requestSequence = 0;

function requestState() {
  if (!stateSocket.isConnected()) {
    return Promise.reject(new Error('Socket is not open'));
  }
  const requestId = `state-${++requestSequence}`;
  return new Promise((resolve, reject) => {
    const deadline = setTimeout(() => reject(new Error('State request timed out')), 5000);
    stateSocket.waitFor(
      raw => {
        try { return JSON.parse(raw).request_id === requestId; }
        catch (_) { return false; }
      },
      raw => {
        clearTimeout(deadline);
        resolve(JSON.parse(raw).data);
      },
      5000,
    );
    stateSocket.sendData(JSON.stringify({operation: 'get_state', request_id: requestId}));
  });
}

stateSocket.connect_handler = async () => {
  try { console.log('Server state:', await requestState()); }
  catch (error) { console.error(error.message); }
};
stateSocket.connect();

2. Send binary data and decode acknowledgement text

Register the binary-ingest handler from the Python guide at /upload/ws. The callback configures each newly opened native socket. This sends one binary frame; the server's acknowledgement is still a JSON text frame.

const binaryScheme = location.protocol === 'https:' ? 'wss' : 'ws';
const transfer = new WebSocketConnection(`${binaryScheme}://${location.host}/upload/ws`);
transfer.connect_handler = () => {
  transfer.socket.binaryType = 'arraybuffer';
  transfer.sendData(new Uint8Array([10, 20, 30]).buffer);
};
transfer.handler = raw => {
  if (typeof raw === 'string') {
    if (raw.startsWith('::')) return;
    try { console.log('Acknowledgement:', JSON.parse(raw)); }
    catch (_) { console.log('Text:', raw); }
  } else if (raw instanceof ArrayBuffer) {
    console.log('Binary response:', new Uint8Array(raw));
  }
};
transfer.connect();

3. Keep an application queue for temporary disconnects

sendData() does not queue messages. This small bounded queue adds that behavior and flushes on native open. It provides no exactly-once guarantee: acknowledgements and replay protection would belong to the application protocol.

const queueScheme = location.protocol === 'https:' ? 'wss' : 'ws';
const queuedSocket = new WebSocketConnection(`${queueScheme}://${location.host}/chat/ws`);
const pending = [];

function sendWhenOpen(text) {
  if (queuedSocket.isConnected()) {
    queuedSocket.sendData(text);
    return true;
  }
  if (pending.length >= 100) return false;
  pending.push(text);
  return true;
}

queuedSocket.connect_handler = () => {
  queuedSocket.sendData('join');
  while (pending.length > 0 && queuedSocket.isConnected()) {
    queuedSocket.sendData(pending.shift());
  }
};
queuedSocket.handler = text => console.log(text);
queuedSocket.connect();
sendWhenOpen('hello');
window.addEventListener('pagehide', () => queuedSocket.disconnect());

Errors, reconnection, and caveats

Practical recipes

Connect to the current host

const scheme = location.protocol === "https:" ? "wss" : "ws";
const socket = new WebSocketConnection(
  `${scheme}://${location.host}/record/ws`
);
socket.connect();

Send after the transport opens

socket.connect_handler = () => {
  socket.sendData(JSON.stringify({ type: "subscribe" }));
};
socket.connect();

connect_handler runs again after a reconnect, which makes it useful for restoring subscriptions. Make the server operation idempotent so a repeated subscription is safe.

Clean up during page teardown

window.addEventListener("pagehide", () => {
  socket.disconnect();
});

Integration checklist

• Load the script before constructing WebSocketConnection.
• Use a PmSocket-compatible server that sends ::connect:: and responds to ::ping::.
• Assign handler and connect_handler before connect().
• Serialize objects with JSON.stringify().
• Use sendData() for guarded sends. It drops messages while disconnected; there is no send queue.
• Call disconnect() for deliberate shutdown.
• Avoid using the four reserved protocol strings as business messages.