home-assistant-js-websocket

The Connection object automatically attempts to reconnect when the connection is lost and resubscribes to event listeners upon reconnection.

Suspend Reconnection

To prevent automatic reconnection until a specific condition is met, pass a promise to suspendReconnectUntil(). Messages sent while suspended will be queued and sent once the connection is re-established. If the first reconnect attempt fails, queued messages are rejected.

connection.suspendReconnectUntil(
  new Promise((resolve) => {
    // Resolve this to allow reconnection
    resolve();
  }),
);

Suspend Connection

To actively close the connection and wait for a promise to resolve before reconnecting, use suspend(). You can also use suspendReconnectUntil() followed by suspend().

connection.suspend(
  new Promise((resolve) => {
    resolve();
  }),
);

Connection Events

Closing

Use connection.close() to close the connection without attempting to reconnect.

To connect to a Home Assistant instance, you must first obtain an authentication token using getAuth(), then pass that token to createConnection(). The library handles the OAuth2 flow and redirection for you. If getAuth() is called without a hassUrl, it will throw ERR_HASS_HOST_REQUIRED, at which point you should prompt the user for their instance URL and retry.

import {
  getAuth,
  createConnection,
  subscribeEntities,
  ERR_HASS_HOST_REQUIRED,
} from "home-assistant-js-websocket";

async function connect() {
  let auth;
  try {
    // Try to pick up authentication after user logs in
    auth = await getAuth();
  } catch (err) {
    if (err === ERR_HASS_HOST_REQUIRED) {
      const hassUrl = prompt(
        "What host to connect to?",
        "http://localhost:8123",
      );
      // Redirect user to log in on their instance
      auth = await getAuth({ hassUrl });
    } else {
      alert(`Unknown error: ${err}`);
      return;
    }
  }
  const connection = await createConnection({ auth });
  subscribeEntities(connection, (ent) => console.log(ent));
}

connect();

The Connection class implements an automatic reconnection strategy with several key behaviors:

Automatic Reconnection

When a connection is lost, the class attempts to reconnect using an exponential backoff strategy (up to 5 attempts, with delays increasing by 1 second per attempt). If createSocket fails with ERR_INVALID_AUTH, it stops retrying and fires the reconnect-error event.

Suspension and Queuing

You can temporarily halt reconnection attempts using suspend() and suspendReconnectUntil(suspendPromise).

When the connection is in a suspended state (e.g., during a network transition or while waiting for a specific condition):

1. The socket is closed.
2. Any calls to sendMessage or sendMessagePromise are placed into an internal _queuedMessages array.
3. Once the suspendPromise resolves, the connection attempts to reconnect.
4. Upon successful reconnection, all queued messages are automatically processed in order.

A connection object obtained via createConnection() is the primary interface for interacting with Home Assistant. It provides methods for sending messages, subscribing to events, and accessing connection metadata.

Key methods:

• conn.haVersion: A string representing the current Home Assistant version.
• conn.subscribeEvents(eventCallback, [eventType]): Subscribes to all or specific events on the Home Assistant bus. Returns a promise that resolves to a cancellation function. Subscriptions are automatically re-established on reconnect.
• conn.sendMessagePromise(message): Sends a message to the server. Returns a promise. If the connection is lost during the operation, it rejects with ERR_CONNECTION_LOST.
• conn.subscribeMessage(callback, subscribeMessage, [options]): Calls a Home Assistant endpoint that creates a subscription. Returns a promise that resolves to a cancellation function. Subscriptions re-establish on reconnect unless options.resubscribe is set to false.

getAuth() manages the OAuth2 flow to fetch an authentication token. It handles redirecting the user to the Home Assistant instance and fetching the token after a successful login.

Options

Errors

getAuth({ hassUrl: "http://localhost:8123" });

You can subscribe to real-time updates for Home Assistant entities, configuration, or services using subscription functions. These functions return an unsubscribe function to stop listening.

Entities

Use subscribeEntities to receive a callback whenever entities are loaded or their states change. The callback receives an object keyed by entity_id.

import { subscribeEntities } from "home-assistant-js-websocket";
subscribeEntities(conn, (entities) => console.log("New entities!", entities));

Alternatively, use entitiesColl for a collection-based approach:

import { entitiesColl } from "home-assistant-js-websocket";
const coll = entitiesColl(conn);
console.log(coll.state);
await coll.refresh();
coll.subscribe((entities) => console.log(entities));

Config

Use subscribeConfig to listen for changes in Home Assistant configuration.

import { subscribeConfig } from "home-assistant-js-websocket";
subscribeConfig(conn, (config) => console.log("New config!", config));

Services

Use subscribeServices to listen for changes in available services.

import { subscribeServices } from "home-assistant-js-websocket";
subscribeServices(conn, (services) => console.log("New services!", services));

getCollection allows you to create a managed data store that handles initial fetching, automatic updates via event subscriptions, and shared listeners. This is useful for pre-loading data before a UI renders.

API Signature

getCollection<State>(
  conn: Connection,
  key: string,
  fetchCollection: (conn: Connection) => Promise<State>,
  subscribeUpdates: (
    conn: Connection,
    store: Store<State>
  ) => Promise<UnsubscribeFunc>,
): Collection<State>

Collection Interface

• state: State: The current state of the collection.
• async refresh(): Promise<void>: Manually triggers a refresh of the data.
• subscribe(subscriber: (state: State) => void): UnsubscribeFunc: Adds a listener to the collection state.

Example: Creating a Panels Collection

import { getCollection } from "home-assistant-js-websocket";

function panelRegistered(state, event) {
  if (state === undefined) return null;
  return {
    panels: state.panels.concat(event.data.panel),
  };
}

const fetchPanels = (conn) => conn.sendMessagePromise({ type: "get_panels" });
const subscribeUpdates = (conn, store) =>
  conn.subscribeEvents(store.action(panelRegistered), "panel_registered");

const panelsColl = getCollection(conn, "_pnl", fetchPanels, subscribeUpdates);

// Usage
console.log(panelsColl.state);
await panelsColl.refresh();
panelsColl.subscribe((panels) => console.log("New panels!", panels));