Migration v1.0

Migration to v1.0

This guide covers breaking changes and new features in the v1.0 release of nut-client.

Breaking Changes

runCommand() return type changed

Before: returned string (raw server response). After: returns CommandResult | TrackedResult (structured object).

// Before (v0.x)
const response = await client.runCommand('myups', 'shutdown.return');
// response = "OK"

// After (v1.0)
const result = await client.runCommand('myups', 'shutdown.return');
// result = { tracked: false, success: true }

If tracking is enabled:

// Before
const response = await client.runCommand('myups', 'shutdown.return');
// response = "OK TRACKING abc-123"

// After
const result = await client.runCommand('myups', 'shutdown.return');
// result = { tracked: true, trackingUid: 'abc-123' }

setVariable() return type changed

Same as runCommand() — now returns CommandResult | TrackedResult instead of string.

VARIABLE_CHANGED event signature changed

Before: (key: string, oldValue: string, newValue: string) After: (key: string, oldValue: string, newValue: string, oldVariables: nutVariables, newVariables: nutVariables)

// Before
monitor.on('VARIABLE_CHANGED', (key, oldValue, newValue) => { ... });

// After — old code still works, but you can now access full variable snapshots
monitor.on('VARIABLE_CHANGED', (key, oldValue, newValue, oldVars, newVars) => { ... });

New Features

Command parameters

runCommand() now accepts an optional param argument:

await client.runCommand('myups', 'shutdown.return', '60');  // 60-second delay

Command tracking

New tracking system for long-running write operations. See Tracking for details.

await client.setTracking(true);
const result = await client.runCommand('myups', 'shutdown.return', '60', {
  followTracking: true,
  trackingTimeout: 60000,
});

New NUTClient methods

// Get UPS description
const desc = await client.getUPSDescription('myups');

// Force shutdown (set FSD flag)
await client.forceShutdown('myups');

// Static factory
const client = await NUTClient.create('127.0.0.1', 3493, {
  username: 'admin',
  password: 'secret',
  autoReconnect: true,
});

// Check connection state
if (client.connected) { ... }

New Monitor events

Additional "NOT" events for flag disappearance:

monitor.on('NOTOL', () => ...);   // OL disappeared
monitor.on('NOTOB', () => ...);   // OB disappeared
monitor.on('NOTLB', () => ...);   // LB disappeared
monitor.on('NOTFSD', () => ...);  // FSD disappeared
monitor.on('NOTRB', () => ...);   // RB disappeared

New variable events:

monitor.on('VARIABLES_CHANGED', (oldVars, newVars) => ...);  // any variable changed
monitor.on('UNKNOWN_STATUS', (status) => ...);                // unrecognized status code

Monitor pause/resume

monitor.pause();       // suppress events
monitor.isPaused();    // check state
monitor.resume();      // resume events
monitor.isDestroyed(); // check lifecycle

New UPS convenience methods

await ups.getInputVoltage();   // input voltage or NaN
await ups.getOutputVoltage();  // output voltage or NaN
await ups.getManufacturer();   // manufacturer string
await ups.getSerial();         // serial number string

Tracking types export

New exported types:

import type { CommandResult, TrackedResult, TrackingOptions } from 'nut-client';

Upgrade Checklist

1. Update import paths if you imported from internal paths — use nut-client directly.
2. Handle runCommand() and setVariable() return values — they are now objects, not strings.
3. Update VARIABLE_CHANGED handlers if you rely on the argument count — the signature gained 2 optional parameters.
4. Enable tracking if you need write confirmation — setTracking(true).
5. Subscribe to NOT* events if you need to react when status flags are cleared.
6. Test auto-reconnect if you rely on connection stability — the reconnect system is now more robust with session restoration.