Apply

The apply() function orchestrates operations across target hosts. It handles connection management, context creation, and multi-host batching.

Single-Host Mode

Connects to a single host, creates a connector context, and runs the function:

import { apply } from 'sysopkit';
import { LocalConnector } from 'sysopkit/connector/local';
import { sh } from 'sysopkit/op/sh';
import { start } from 'sysopkit/start';

await start(async () => {
  await using c = new LocalConnector();

  const result = await apply('setup', c, async () => {
    await sh('hostname');
    return 'done';
  });
  // result: { success: true, conn: c, result: 'done' }
});

Multi-Host Mode

Processes multiple hosts in parallel batches:

import { apply } from 'sysopkit';
import { resolveInventory } from 'sysopkit/inventory';
import { start } from 'sysopkit/start';

const inventory = {
  groups: {
    web: {
      hosts: {
        'web-1': { host: '10.0.1.1' },
        'web-2': { host: '10.0.1.2' },
        'web-3': { host: '10.0.1.3' },
      },
    },
  },
};

await start(async () => {
  await using hosts = resolveInventory(inventory);

  const results = await apply(
    'setup web',
    hosts.getByGroup('web'),
    async () => {
      await sh('hostname');
    },
    { batchSize: 2, maxFailPercent: 20 },
  );
  // results: ApplyResult<void>[]
});

Options

Option	Default	Description
batchSize	5	Hosts per parallel batch (>= 1 or Infinity for one giant batch)
maxFailPercent	—	Abort remaining batches if failure % exceeds this threshold
vars	—	Additional context variables

Error Handling

In multi-host mode, failures are collected per host. If maxFailPercent is exceeded, apply() throws ApplyError (extends AggregateError) containing all per-host results:

import { apply, ApplyError } from 'sysopkit';
import { start } from 'sysopkit/start';

await start(async (ctx) => {
  try {
    await apply('setup', hosts.getAll(), fn, { maxFailPercent: 20 });
  } catch (err) {
    if (err instanceof ApplyError) {
      for (const result of err.results) {
        if (!result.success) {
          ctx.error(`${result.conn.name} failed: ${result.error}`);
        }
      }
    }
    throw err;
  }
});

Inside start() (which apply requires) always report via ctx/context() — never console.*. console.* is only for code outside start(), where no context exists.