https://github.com/hyperse-io/exec-program
Executes a command using `file ...arguments`, supports `.ts` file with esm type module.
https://github.com/hyperse-io/exec-program
bin exec execa execfile hyperse process run-ts-files shell spawn swc-node
Last synced: about 2 months ago
JSON representation
Executes a command using `file ...arguments`, supports `.ts` file with esm type module.
- Host: GitHub
- URL: https://github.com/hyperse-io/exec-program
- Owner: hyperse-io
- License: mit
- Created: 2024-05-25T09:16:50.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-10T09:12:19.000Z (7 months ago)
- Last Synced: 2025-08-08T17:58:26.077Z (5 months ago)
- Topics: bin, exec, execa, execfile, hyperse, process, run-ts-files, shell, spawn, swc-node
- Language: JavaScript
- Homepage:
- Size: 3.54 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# @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](#installation)
- [Features](#features)
- [API Reference](#api-reference)
- [runTsScript](#runtsscript)
- [execute](#execute)
- [Usage Examples](#usage-examples)
- [Running TypeScript Files](#running-typescript-files)
- [Executing Commands](#executing-commands)
- [Unit Testing with Vitest](#unit-testing-with-vitest)
- [Configuration](#configuration)
## Installation
```bash
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.
```typescript
/**
* 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: (
program: string,
args?: readonly string[],
options?: T
) => ExecResultPromise<{} & T>;
```
### execute
Executes a shell command with specified arguments and options.
```typescript
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(
file: string,
args?: readonly string[],
options?: T
): ExecResultPromise<{} & T>;
```
## Usage Examples
### Running TypeScript Files
```typescript
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
```typescript
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`:
```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`):
```typescript
import { runTsScript } from '@hyperse/exec-program';
console.log(typeof runTsScript);
console.log('cli...');
```
3. Write your test (`main.spec.ts`):
```typescript
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.