yocto-client

Standard client for the Yoctopus server with event emitter support.

Installation

npm install yocto-client

Usage

Event-based API (recommended)

import YoctoClient from 'yocto-client';

const client = new YoctoClient({
  url: 'ws://localhost:3000',
  autoReconnectTimeMs: 5000,
  verbose: false,
});

// Subscribe to events
client.on('connected', () => console.log('Connected'));
client.on('disconnected', () => console.log('Disconnected'));
client.on('notification', (msg) => console.log('Server push:', msg));
client.on('requests', ({ pending }) => console.log('Pending:', pending));
client.on('error', (err) => console.error(err));
client.on('reconnecting', ({ attempt, delay }) => console.log(`Reconnect attempt ${attempt}`));

// State change events
client.on('state', ({ state, previousState }) => {
  console.log(`${previousState} → ${state}`);
});

// Request lifecycle events (for debugging/logging)
client.on('request:start', ({ id, endpoint, method }) => {});
client.on('request:end', ({ id, endpoint, method, duration, success }) => {});
client.on('request:error', ({ id, endpoint, method, error }) => {});

// Connect and make requests
await client.connect();
const response = await client.request({ endpoint: 'users', method: 'read', data: { id: 123 } });

// One-time listener
client.once('connected', () => initApp());

// Remove listener
const handler = () => {};
const unsubscribe = client.on('connected', handler);
unsubscribe(); // or: client.off('connected', handler);

// Cleanup
client.destroy();

Legacy Callback API (backward compatible)

const client = new YoctoClient({
  url: 'ws://localhost:3000',
  onConnected: () => console.log('Connected'),
  onDisconnected: () => console.log('Disconnected'),
  onNotification: (msg) => console.log('Notification:', msg),
  onRequestsChanged: ({ pending }) => console.log('Pending:', pending),
});

await client.connect();

API

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string \| URL | required | WebSocket URL (ws:// or wss://) | | name | string | 'unnamed connection' | Connection name for logging | | autoReconnectTimeMs | number | 5000 | Auto-reconnect delay in ms | | connectionTimeoutMs | number | 3000 | Connection timeout in ms | | verbose | boolean | false | Enable debug logging |

Events

| Event | Payload | Description | |-------|---------|-------------| | connected | - | Connection established | | disconnected | - | Connection lost | | notification | Object | Server push message | | requests | { pending: number } | Pending request count changed | | error | Error | Error occurred | | reconnecting | { attempt: number, delay: number } | Reconnection attempt | | state | { state: string, previousState: string } | Connection state changed | | request:start | { id, endpoint, method } | Request started | | request:end | { id, endpoint, method, duration, success } | Request completed | | request:error | { id, endpoint, method, error } | Request failed |

Methods

client.on(event, callback)

Subscribe to an event. Returns an unsubscribe function.

client.once(event, callback)

Subscribe to an event once (auto-unsubscribes after first call).

client.off(event, callback)

Unsubscribe from an event.

client.removeAllListeners([event])

Remove all listeners for an event, or all events if no event specified.

client.connect()

Connect to the WebSocket server. Returns a Promise.

client.request(options)

Send a request to the server. Returns a Promise with the response.

Options:

• endpoint (string, required): Target endpoint
• method (string, default: 'read'): Request method
• data (object, default: {}): Request payload
• timeout (number, default: 30000): Request timeout in ms

client.destroy()

Disconnect and clean up. Prevents further reconnection attempts.

Properties

| Property | Type | Description | |----------|------|-------------| | connected | boolean | Whether currently connected | | state | string | Current state: 'connecting', 'connected', 'closing', 'closed' | | pendingRequests | number | Number of pending requests | | url | URL | Server URL |

Development

Installation

# Linux (full installation including yoctopus)
npm install

# macOS/Windows (skip native module compilation)
npm install --ignore-scripts

Testing

# Unit tests (works on all platforms, uses mock WebSocket server)
npm test

# Integration tests (Linux only, requires yoctopus)
npm run test:integration

# All tests
npm run test:all

Building

npm run build

License

ISC