346 lines
12 KiB
Markdown
346 lines
12 KiB
Markdown
# @git.zone/tsrun
|
|
|
|
[](https://www.npmjs.com/package/@git.zone/tsrun)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://nodejs.org/)
|
|
|
|
> Run TypeScript files instantly — no build step, no config, no friction ⚡
|
|
|
|
Execute TypeScript programs on-the-fly with zero configuration. Whether you're writing quick scripts, prototyping ideas, or orchestrating complex multi-project workflows, tsrun gets out of your way and lets you focus on code.
|
|
|
|
## Issue Reporting and Security
|
|
|
|
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
|
|
|
## Table of Contents
|
|
|
|
- [What is tsrun?](#what-is-tsrun)
|
|
- [Installation](#installation)
|
|
- [CLI Usage](#-cli-usage)
|
|
- [Programmatic API](#-programmatic-api)
|
|
- [runPath()](#runpath---simple-execution)
|
|
- [runCli()](#runcli---cli-mode)
|
|
- [spawnPath()](#spawnpath---advanced-process-control)
|
|
- [API Quick Reference](#api-quick-reference)
|
|
- [Features](#features)
|
|
- [Common Use Cases](#common-use-cases)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [License and Legal Information](#license-and-legal-information)
|
|
|
|
## What is tsrun?
|
|
|
|
**tsrun** is a lightweight TypeScript execution tool that lets you run `.ts` files directly — just like running JavaScript with `node`, but for TypeScript. Under the hood, it uses [tsx](https://github.com/privatenumber/tsx) for lightning-fast transpilation, so there's no compilation step, no tsconfig fiddling, and no waiting around.
|
|
|
|
It also doubles as a **programmatic library** with full process control — spawn TypeScript processes, capture their output, set timeouts, and cancel them with `AbortController`. Perfect for build scripts, task runners, and orchestration tools.
|
|
|
|
## Installation
|
|
|
|
**Global** (recommended for CLI usage):
|
|
|
|
```bash
|
|
pnpm install -g @git.zone/tsrun
|
|
```
|
|
|
|
**As a project dependency** (for programmatic API):
|
|
|
|
```bash
|
|
pnpm install @git.zone/tsrun
|
|
```
|
|
|
|
## 🚀 CLI Usage
|
|
|
|
Run any TypeScript file:
|
|
|
|
```bash
|
|
tsrun myScript.ts
|
|
```
|
|
|
|
Arguments pass through transparently, just like `node`:
|
|
|
|
```bash
|
|
tsrun deploy.ts production --verbose --dry-run
|
|
```
|
|
|
|
Your script sees them in `process.argv` as expected:
|
|
|
|
```typescript
|
|
// deploy.ts
|
|
const env = process.argv[0]; // "production"
|
|
const verbose = process.argv.includes('--verbose');
|
|
const dryRun = process.argv.includes('--dry-run');
|
|
|
|
console.log(`Deploying to ${env}...`);
|
|
```
|
|
|
|
## 💻 Programmatic API
|
|
|
|
tsrun exports three functions tailored for different execution needs.
|
|
|
|
### `runPath()` — Simple Execution
|
|
|
|
Runs a TypeScript file and waits for it to complete. The simplest way to execute scripts programmatically.
|
|
|
|
```typescript
|
|
import { runPath } from '@git.zone/tsrun';
|
|
|
|
// Run a script (path relative to cwd)
|
|
await runPath('./scripts/build.ts');
|
|
|
|
// Resolve path relative to the calling file
|
|
await runPath('./build.ts', import.meta.url);
|
|
|
|
// Run in a different working directory (spawns a child process)
|
|
await runPath('./build.ts', import.meta.url, { cwd: '/path/to/project' });
|
|
```
|
|
|
|
**How it works:**
|
|
- Without `cwd` — executes **in-process** using tsx's ESM loader (fast, zero overhead)
|
|
- With `cwd` — spawns an **isolated child process** with the given working directory
|
|
|
|
### `runCli()` — CLI Mode
|
|
|
|
Runs with `process.argv` integration, as if the script were invoked from the command line. This is what the `tsrun` CLI binary uses internally.
|
|
|
|
```typescript
|
|
import { runCli } from '@git.zone/tsrun';
|
|
|
|
// Uses process.argv for argument passing
|
|
await runCli('./script.ts');
|
|
|
|
// With custom working directory
|
|
await runCli('./script.ts', { cwd: '/path/to/project' });
|
|
```
|
|
|
|
### `spawnPath()` — Advanced Process Control
|
|
|
|
Returns immediately with a process handle, giving you full control over stdio, timeouts, and cancellation.
|
|
|
|
```typescript
|
|
import { spawnPath } from '@git.zone/tsrun';
|
|
|
|
const proc = spawnPath('./task.ts', import.meta.url, {
|
|
timeout: 30000, // Kill after 30s
|
|
cwd: '/path/to/project',
|
|
env: { NODE_ENV: 'production' }, // Merged with process.env
|
|
args: ['--verbose'], // Extra CLI args
|
|
stdio: 'pipe', // Default: capture stdout/stderr
|
|
});
|
|
|
|
// Stream stdout
|
|
proc.stdout?.on('data', (chunk) => {
|
|
console.log(chunk.toString());
|
|
});
|
|
|
|
// Wait for exit
|
|
const exitCode = await proc.exitCode;
|
|
```
|
|
|
|
**AbortController support:**
|
|
|
|
```typescript
|
|
const controller = new AbortController();
|
|
const proc = spawnPath('./task.ts', import.meta.url, {
|
|
signal: controller.signal,
|
|
});
|
|
|
|
// Cancel from outside
|
|
setTimeout(() => controller.abort(), 5000);
|
|
|
|
try {
|
|
await proc.exitCode;
|
|
} catch (err) {
|
|
console.log('Process was cancelled');
|
|
}
|
|
```
|
|
|
|
**Graceful termination:**
|
|
|
|
```typescript
|
|
const proc = spawnPath('./server.ts', import.meta.url);
|
|
|
|
// Sends SIGTERM, waits 5s, then SIGKILL if still running
|
|
await proc.terminate();
|
|
```
|
|
|
|
## API Quick Reference
|
|
|
|
| Function | Execution | Returns | Best For |
|
|
|----------|-----------|---------|----------|
|
|
| `runPath()` | In-process (or child with `cwd`) | `Promise<void>` | Simple script execution, sequential workflows |
|
|
| `runCli()` | In-process (or child with `cwd`) | `Promise<void>` | CLI-like invocation with argv integration |
|
|
| `spawnPath()` | Always child process | `ITsrunChildProcess` | Output capture, timeouts, cancellation, parallel tasks |
|
|
|
|
**Decision guide:**
|
|
- 🎯 **Just run a script?** → `runPath()`
|
|
- 🔧 **Need argv pass-through?** → `runCli()`
|
|
- 🎛️ **Need stdout/stderr, timeout, or cancel?** → `spawnPath()`
|
|
- ⚡ **Parallel execution across projects?** → `runPath()` with `cwd` or `spawnPath()`
|
|
|
|
### `ITsrunChildProcess` Interface
|
|
|
|
The object returned by `spawnPath()`:
|
|
|
|
| Property / Method | Type | Description |
|
|
|---|---|---|
|
|
| `childProcess` | `ChildProcess` | Direct access to Node's ChildProcess |
|
|
| `stdout` | `Readable \| null` | Stdout stream (`null` if stdio is `'inherit'`) |
|
|
| `stderr` | `Readable \| null` | Stderr stream (`null` if stdio is `'inherit'`) |
|
|
| `exitCode` | `Promise<number>` | Resolves with exit code when process ends |
|
|
| `kill(signal?)` | `(signal?: NodeJS.Signals) => boolean` | Send a signal to the process |
|
|
| `terminate()` | `() => Promise<void>` | Graceful shutdown: SIGTERM → 5s → SIGKILL |
|
|
|
|
### `ISpawnOptions`
|
|
|
|
Options for `spawnPath()`:
|
|
|
|
| Option | Type | Default | Description |
|
|
|---|---|---|---|
|
|
| `cwd` | `string` | `process.cwd()` | Working directory for the child process |
|
|
| `env` | `Record<string, string>` | `{}` | Extra env vars (merged with `process.env`) |
|
|
| `args` | `string[]` | `[]` | Additional CLI arguments |
|
|
| `stdio` | `'pipe' \| 'inherit'` | `'pipe'` | Stdio configuration |
|
|
| `timeout` | `number` | — | Auto-kill after N milliseconds |
|
|
| `signal` | `AbortSignal` | — | External cancellation support |
|
|
|
|
## Features
|
|
|
|
✨ **Zero Configuration** — Point and shoot. No tsconfig required, no build step, no setup.
|
|
|
|
⚡ **Lightning Fast** — Powered by tsx (esbuild under the hood) for near-instant TypeScript execution.
|
|
|
|
🔄 **Transparent Arguments** — CLI args pass through seamlessly to your scripts via `process.argv`.
|
|
|
|
📦 **Dual Interface** — Use as a CLI tool or import as a library with full TypeScript types.
|
|
|
|
🔀 **Custom Working Directory** — Run scripts in isolated child processes with different cwds.
|
|
|
|
🎛️ **Full Process Control** — `spawnPath()` gives you streams, timeouts, cancellation, and graceful shutdown.
|
|
|
|
🛡️ **Signal Forwarding** — SIGINT/SIGTERM/SIGHUP are properly forwarded to child processes.
|
|
|
|
## Common Use Cases
|
|
|
|
### Quick Scripts & Prototyping
|
|
|
|
```bash
|
|
# Write TypeScript, run it immediately
|
|
tsrun seed-database.ts
|
|
tsrun generate-report.ts --format csv
|
|
tsrun cleanup-temp-files.ts
|
|
```
|
|
|
|
### Sequential Build Pipeline
|
|
|
|
```typescript
|
|
import { runPath } from '@git.zone/tsrun';
|
|
|
|
const steps = ['./lint.ts', './test.ts', './build.ts', './deploy.ts'];
|
|
|
|
for (const step of steps) {
|
|
console.log(`▶ Running ${step}...`);
|
|
await runPath(step, import.meta.url);
|
|
console.log(`✓ Done`);
|
|
}
|
|
```
|
|
|
|
### Parallel Multi-Project Builds
|
|
|
|
```typescript
|
|
import { runPath } from '@git.zone/tsrun';
|
|
|
|
await Promise.all([
|
|
runPath('./build.ts', undefined, { cwd: '/workspace/frontend' }),
|
|
runPath('./build.ts', undefined, { cwd: '/workspace/backend' }),
|
|
runPath('./build.ts', undefined, { cwd: '/workspace/shared' }),
|
|
]);
|
|
```
|
|
|
|
### Long-Running Tasks with Monitoring
|
|
|
|
```typescript
|
|
import { spawnPath } from '@git.zone/tsrun';
|
|
|
|
const proc = spawnPath('./data-migration.ts', import.meta.url, {
|
|
timeout: 300000, // 5 minute max
|
|
env: { LOG_LEVEL: 'verbose' },
|
|
});
|
|
|
|
let lines = 0;
|
|
proc.stdout?.on('data', (chunk) => {
|
|
lines++;
|
|
if (lines % 100 === 0) console.log(`Processed ${lines} lines...`);
|
|
});
|
|
|
|
try {
|
|
await proc.exitCode;
|
|
console.log('Migration completed!');
|
|
} catch (err) {
|
|
console.error('Migration failed:', err.message);
|
|
process.exit(1);
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Cannot find module" errors
|
|
|
|
Use `import.meta.url` for path resolution relative to the calling file:
|
|
|
|
```typescript
|
|
// ❌ Relative to cwd — fragile
|
|
await runPath('./script.ts');
|
|
|
|
// ✅ Relative to current file — reliable
|
|
await runPath('./script.ts', import.meta.url);
|
|
```
|
|
|
|
### Process hangs
|
|
|
|
When using `spawnPath()`, always await the `exitCode` promise:
|
|
|
|
```typescript
|
|
const proc = spawnPath('./script.ts', import.meta.url);
|
|
await proc.exitCode; // Don't forget this!
|
|
```
|
|
|
|
### Timeout only works with `spawnPath()`
|
|
|
|
`runPath()` executes in-process and doesn't support timeouts. Use `spawnPath()` instead:
|
|
|
|
```typescript
|
|
const proc = spawnPath('./script.ts', import.meta.url, { timeout: 5000 });
|
|
await proc.exitCode;
|
|
```
|
|
|
|
### `tsrun: command not found`
|
|
|
|
Install globally or use `npx`:
|
|
|
|
```bash
|
|
pnpm install -g @git.zone/tsrun
|
|
# or
|
|
npx @git.zone/tsrun myScript.ts
|
|
```
|
|
|
|
## License and Legal Information
|
|
|
|
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
|
|
|
|
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
|
|
|
### Trademarks
|
|
|
|
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
|
|
|
|
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
|
|
|
### Company Information
|
|
|
|
Task Venture Capital GmbH
|
|
Registered at District Court Bremen HRB 35230 HB, Germany
|
|
|
|
For any legal inquiries or further information, please contact us via email at hello@task.vc.
|
|
|
|
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|