@hyperse/exec-program

A Node.js utility for programmatically executing commands in your scripts, applications, or libraries. Unlike traditional shells, it's optimized for programmatic usage with TypeScript support.

Table of Contents

• Installation
• Features
• API Reference
  • runTsScript
  • execute
• Usage Examples
  • Running TypeScript Files
  • Executing Commands
  • Unit Testing with Vitest
• Configuration

Installation

npm install --save @hyperse/exec-program

Features

• 🚀 Execute TypeScript files directly
• 💻 Run shell commands programmatically
• 📘 TypeScript support out of the box
• ⚡ Promise-based API
• ⚙️ Configurable execution options
• 🧪 Built-in support for unit testing

API Reference

runTsScript

Executes a TypeScript file and returns its output.

/**
 * Process execute typescript script file using `@hyperse/ts-node`
 * @param program - The absolute typescript file path
 * @param options - The configuration of `execa` { env: { HPS_TS_NODE_PROJECT: tsconfig } }
 * @param args - The runtime argv for program
 */
declare const runTsScript: <T extends ExecOptions>(
  program: string,
  args?: readonly string[],
  options?: T
) => ExecResultPromise<{} & T>;

execute

Executes a shell command with specified arguments and options.

import { execute } from '@hyperse/exec-program';

/**
 * Execute a file with arguments and options
 * @param file - The program/script to execute, as a string or file URL
 * @param args - Arguments to pass to `file` on execution.
 * @param options - Options to pass to `execa`
 * @returns A `ResultPromise` that is both:
 */
declare function execute<T extends ExecOptions>(
  file: string,
  args?: readonly string[],
  options?: T
): ExecResultPromise<{} & T>;

Usage Examples

Running TypeScript Files

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { runTsScript } from '@hyperse/exec-program';

const getDirname = (url: string, ...paths: string[]) => {
  return join(dirname(fileURLToPath(url)), ...paths);
};

// Execute a TypeScript file
const cliPath = getDirname(import.meta.url, './cli-test.ts');
const { stderr, stdout } = await runTsScript(cliPath);
console.log(stderr, stdout);

Executing Commands

import { execute } from '@hyperse/exec-program';

// Install npm packages
const { stdout, stderr } = await execute(
  'npm',
  ['i', '--no-save', '--no-package-lock', ...packages],
  {
    cwd: targetDirectory,
    maxBuffer: TEN_MEGA_BYTE,
    env: npmEnv,
  }
);

// Create npm package
await execute('npm', ['pack', directory], {
  cwd: uniqueDir,
  maxBuffer: TEN_MEGA_BYTE,
});

Unit Testing with Vitest

1. Configure your tsconfig.json:

{
  "extends": "@hyperse/eslint-config-hyperse/tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "./src",
    "rootDir": "./",
    "outDir": "dist",
    "types": ["vitest/globals"],
    "paths": {
      "@hyperse/exec-program": ["../src/index.js"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"]
}

2. Create a test file (cli-test.ts):

import { runTsScript } from '@hyperse/exec-program';

console.log(typeof runTsScript);
console.log('cli...');

3. Write your test (main.spec.ts):

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { runTsScript } from '@hyperse/exec-program';

const getDirname = (url: string, ...paths: string[]) => {
  return join(dirname(fileURLToPath(url)), ...paths);
};

const cliPath = getDirname(import.meta.url, './cli-test.ts');

describe('test suites of exec program', () => {
  it('should correctly invoke cli.ts', async () => {
    const { stderr, stdout } = await runTsScript(cliPath);
    expect(stderr).toBe('');
    expect(stdout).toMatch(/cli.../);
  });
});

Configuration

The library supports various configuration options for both runTsScript and execute functions. These options allow you to customize the execution environment, working directory, and other parameters.

For detailed configuration options, please refer to the TypeScript types in the source code.