run.js

import { spinner } from "./spinner.js";

/**
 * Run an async function wrapped in a spinner.
 * The spinner starts automatically, resolves to the function's return value
 * on success, or rethrows on failure (after displaying an error state).
 *
 * This is a convenience wrapper around `spinner()` for one-shot async tasks.
 * For tracking *multiple* concurrent tasks, use `tasks()` instead.
 *
 * @template T
 * @param {string} label                    Label shown while the task runs.
 * @param {() => Promise<T>} fn             Async work to execute.
 * @param {import("./spinner.js").SpinnerOptions} [options]
 * @returns {Promise<T>}
 *
 * @example
 * const data = await run("Fetching data", () => fetchData());
 *
 * @example
 * // Custom spinner style
 * await run("Building", build, { style: "line", color: "magenta" });
 */
export async function run(label, fn, options = {}) {
  const spin = spinner(label, options);
  spin.start();
  try {
    const result = await fn();
    spin.success();
    return result;
  } catch (err) {
    spin.error(err?.message ?? String(err));
    throw err;
  }
}