velo.watch

Opens a live subscription from a completed subscription request. The connection starts immediately, and the returned promise resolves with a reusable watcher once the subscription is live.

Currently, news.feed() is the supported subscription request.

Imports

import { Velo } from 'velo-sdk';

Example

Pass listeners with the initial call so they are attached before the connection opens:

import { Velo, news } from 'velo-sdk';
 
const velo = new Velo({ apiKey: process.env.VELO_API_KEY! });
 
const watcher = await velo.watch(news.feed(), {
  on: {
    story: (story) => console.log('New:', story.headline),
    edit: (story) => console.log('Edited:', story.headline),
    delete: ({ id }) => console.log('Deleted:', id),
    error: (error) => console.error(error),
  },
});
 
// Permanently close the subscription when it is no longer needed.
watcher.close();

on can instead be one listener receiving every event as a discriminated union:

const watcher = await velo.watch(news.feed(), {
  on: (event) => {
    if (event.type === 'story') {
      console.log(event.event.headline);
    }
  },
});

Definition

function watch<K extends WatchableKind, P extends WatchParams<K>>(
  input: WatchInput<K, P>,
  options?: WatchOptions<K>,
): Promise<Watcher<K>>;

Parameters

input

Type: WatchInput<K, P>

A direct subscription request or completed subscription builder. Query requests cannot be watched; pass them to velo.query() or, when supported, velo.stream().

options

Type: WatchOptions<K>
Optional

The available event listeners and connection settings are inferred from the subscription kind. For news.feed(), the options are:

Property	Type	Description
`on`	listeners	A map of per-event listeners, or one function receiving every event tagged with `type`.
`reconnect`	`boolean \| Partial<ResumeOptions>`	Controls retries for the initial connection and automatic reconnection after unexpected drops. Enabled by default.
`signal`	`AbortSignal`	Permanently closes the watcher when aborted, including during an initial connection or backoff.
`heartbeatTimeout`	`number`	Maximum time between heartbeat messages in milliseconds. Defaults to `300_000`.
`connectTimeout`	`number`	Maximum time for each connection attempt in milliseconds. Defaults to `30_000`.
`onListenerError`	`(error: unknown) => unknown`	Handles errors thrown or rejected by event listeners.

Listeners supplied through on are attached before connecting, so an event cannot arrive between opening the subscription and registering its initial listeners.

Reconnection

Automatic reconnection uses jittered exponential backoff:

`reconnect` value	Behavior
Omitted or `true`	Retries until the initial connection succeeds and reconnects indefinitely after unexpected drops.
`false`	Makes one initial attempt and does not reconnect after a drop.
An options object	Overrides `retries`, `baseDelayMs`, or `maxDelayMs`. Omitting `retries` keeps retrying.

The default base delay is 500 milliseconds and the maximum delay is 30_000 milliseconds. When retries is set, the initial sequence consists of one immediate attempt followed by at most that many retries. Each outage after a successful connection receives a fresh retry budget.

Intentional endings do not reconnect: disconnect() leaves the watcher reusable, while close() and aborting signal close it permanently. Events missed while disconnected are not replayed.

Return Type

Type: Promise<Watcher<K>>

The promise resolves the first time the subscription becomes live. With the default reconnect policy, it remains pending while failed initial connections are retried. It rejects when reconnection is disabled, a bounded retry budget is exhausted, or the operation is aborted before connecting.

The resolved watcher exposes a read-only state and the following methods:

Member	Description
`state`	One of `idle`, `connecting`, `open`, `disconnected`, or `closed`.
`.on(type, listener)`	Adds a listener and returns the watcher.
`.off(type, listener)`	Removes a listener and returns the watcher.
`.connect()`	Reopens an intentionally disconnected watcher. Concurrent calls share one attempt.
`.disconnect()`	Disconnects intentionally while keeping the watcher and listeners reusable.
`.close()`	Permanently closes the watcher and clears its listeners. Calling it repeatedly is safe.

See news.feed() for the news event payloads and reconnection caveats.

Errors

Invalid options throw synchronously. Connection failures during the initial sequence reject the promise only after reconnection is disabled or its retry budget is exhausted. Failures after the watcher has opened are delivered through its typed error event while automatic reconnection continues according to the selected policy.

Errors from user listeners do not close the connection. They are passed to onListenerError, or reported through the runtime's default error reporting when no handler is supplied.