Resin CLI Visuals

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to use `require()` to import an ES Module package (resin-cli-visuals >= v4.0.0).
  fix Change `const visuals = require('resin-cli-visuals');` to `import { visuals } from 'resin-cli-visuals';`. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions.

• TypeError: visuals.SpinnerPromise is not a constructor

  cause Using the `SpinnerPromise` class constructor directly after v4.0.0.
  fix Replace `new visuals.SpinnerPromise(options)` with `visuals.createSpinnerPromise(options)` as it was changed to a factory function.

• Error: Cannot find module 'resin-cli-visuals'

  cause Incorrect Node.js version. The package specifies `engines.node` requirements.
  fix Check your Node.js version (`node -v`) and ensure it meets the `>=20.0` requirement for v4.x of `resin-cli-visuals`. Upgrade Node.js if needed.

Warnings

• breaking The package migrated entirely to ES Modules (ESM) and TypeScript in v4.0.0. CommonJS `require()` statements will no longer work, and consumers must use `import` syntax.
  Fix: Update all `require()` calls to `import` statements. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension) and transpiles TypeScript if necessary.
• breaking Node.js version requirements increased significantly. v4.x requires Node.js >=20.0, v3.x required >=18.0, and v2.x also required >=18.0.
  Fix: Ensure your Node.js environment meets or exceeds the minimum version specified (>=20.0 for v4.x). Upgrade Node.js if running an older version.
• breaking The `SpinnerPromise` class was replaced with a `createSpinnerPromise` factory function in v4.0.0. The direct `new SpinnerPromise()` constructor is no longer available.
  Fix: Replace `new visuals.SpinnerPromise(...)` with `visuals.createSpinnerPromise(...)`.
• breaking The `chalk` dependency was dropped and replaced with `ansis` in v3.0.1. While `ansis` aims for `chalk` compatibility, direct imports or specific configurations related to `chalk` might break.
  Fix: If you directly used `chalk` via `resin-cli-visuals` exports (which is unlikely as it was an internal dependency) or had custom `chalk` setups interacting with `resin-cli-visuals`, you might need to adjust for `ansis`. Check `ansis` documentation for differences if issues arise.
• breaking The internal `lodash` dependency was removed in v4.0.4. While this should primarily affect internal implementation, if any consumers relied on transitive `lodash` access via `resin-cli-visuals` (an anti-pattern), it would now be missing.
  Fix: Ensure `lodash` is explicitly listed as a dependency in your project's `package.json` if your code directly depends on it, rather than relying on transitive inclusion.

Install

• npm install resin-cli-visuals npm
• yarn add resin-cli-visuals yarn
• pnpm add resin-cli-visuals pnpm

Imports

• visuals
  wrong:

  const visuals = require('resin-cli-visuals');

  correct:

  import { visuals } from 'resin-cli-visuals';

  Package transitioned to ES Modules (ESM) in v4.0.0. CommonJS `require` is no longer supported.
• DriveScanner
  wrong:

  import DriveScanner from 'resin-cli-visuals/build/DriveScanner';

  correct:

  import { DriveScanner } from 'resin-cli-visuals';

  DriveScanner is a named export. All sources were converted to TypeScript and ESM in v4.0.0.
• Spinner
  wrong:

  import { Spinner } from 'resin-cli-visuals';

  correct:

  import { visuals } from 'resin-cli-visuals';
  const spinner = new visuals.Spinner('Loading...');

  Spinner is a member of the `visuals` namespace object, not a top-level export.

Quickstart

This quickstart demonstrates creating a spinner, displaying data in a horizontal table, and using the DriveScanner to detect drive changes.

import { visuals, DriveScanner } from 'resin-cli-visuals';

async function runCliDemo() {
  // Simulate a long-running operation with a spinner
  const spinner = new visuals.Spinner('Processing task...');
  spinner.start();
  await new Promise(resolve => setTimeout(resolve, 3000));
  spinner.stop();
  console.log('Task completed.');

  // Display data in a horizontal table
  const tableData = [
    { label: 'Name', value: 'John Doe' },
    { label: 'Email', value: 'john.doe@example.com' },
    { label: 'Role', value: 'Developer' }
  ];
  const tableOrdering = ['label', 'value'];
  console.log('\nUser Details:');
  console.log(visuals.table.horizontal(tableData, tableOrdering));

  // Example of a DriveScanner (requires a driveFinder function)
  // In a real scenario, driveFinder would be an async function
  // that returns an array of drive objects.
  const mockDriveFinder = async () => [
    { device: '/dev/sda', size: '10GB', description: 'USB Drive' },
    { device: '/dev/sdb', size: '500GB', description: 'Internal HDD' }
  ];
  const scanner = new DriveScanner(mockDriveFinder, { interval: 2000 });
  scanner.on('change', (drives) => {
    console.log('\nDrive change detected:', drives);
  });
  console.log('\nDrive scanner started. Waiting for changes (runs for 5s)...');
  await new Promise(resolve => setTimeout(resolve, 5000));
  scanner.stop();
  console.log('Drive scanner stopped.');
}

runCliDemo().catch(console.error);