npm package: @git.zone/tsrun
Description: run typescript programs efficiently
Author: Lossless GmbH
Latest version: 2.0.2

# @git.zone/tsrun

[![npm version](https://img.shields.io/npm/v/@git.zone/tsrun.svg)](https://www.npmjs.com/package/@git.zone/tsrun)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-native-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green)](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.