YAML-driven task runner for TypeScript files
npm install @noego/captainA lightweight, easy-to-use task scheduler for running TypeScript files and shell commands with cron expressions.
``bash`Install from npm
npm install -g captain
Create a TypeScript task:
`typescript`
// task.ts
console.log("Task running at:", new Date());
Create a task configuration:
`yaml`tasks.yaml
tasks:
simple:
description: "A simple job that runs every minute"
schedule: " *"
file: "./task.ts"
Run Captain:
`bash`
captain ./tasks.yaml
Create a task configuration with shell commands:
`yaml`tasks.yaml
tasks:
health_check:
description: "Check API health every minute"
schedule: " *"
command: "curl -s https://httpbin.org/get"
Run Captain:
`bash`
captain ./tasks.yaml
`bashGlobal installation (recommended for CLI usage)
npm install -g captain
Usage Guide
$3
Create TypeScript files for your scheduled tasks:
`typescript
// tasks/log-metrics.ts
import fs from 'fs';// Access environment variables from YAML config
const logPath = process.env.LOG_PATH || './metrics.log';
// Log system metrics
const metrics = {
timestamp: new Date().toISOString(),
memoryUsage: process.memoryUsage(),
uptime: process.uptime()
};
// Append to log file
fs.appendFileSync(logPath, JSON.stringify(metrics) + '\n');
console.log(
Metrics logged to ${logPath});
`$3
Create a YAML configuration file defining your tasks:
`yaml
scheduler.yaml
tasks:
metrics_logger:
description: "Log system metrics every 15 minutes"
schedule: "/15 *"
file: "./tasks/log-metrics.ts"
timeout: 30 # seconds
env:
LOG_PATH: "./logs/system-metrics.log"
cleanup_task:
description: "Clean up temp files daily at midnight"
schedule: "0 0 *"
file: "./tasks/cleanup.ts"
concurrency:
max: 1
allow_overlap: false # Shell command example
health_check:
description: "Check API health every 5 minutes"
schedule: "/5 *"
command: "curl -s https://api.example.com/health"
timeout: 10
backup:
description: "Run backup script daily"
schedule: "0 2 *"
command: "./scripts/backup.sh"
config:
default_timeout: 60
log_level: "info"
`$3
`bash
Start the scheduler
captain ./scheduler.yamlList all configured tasks
captain ./scheduler.yaml --listRun a specific task immediately
captain ./scheduler.yaml --run metrics_loggerCombine multiple configuration files
captain ./system-tasks.yaml ./app-tasks.yaml
`Task Configuration Reference
Each task supports the following options:
| Option | Type | Required | Description |
|--------|------|----------|-------------|
|
description | string | No | Human-readable description of the task |
| schedule | string | Yes | Cron expression (e.g. "/5 *") |
| file | string | No* | Path to TypeScript file to execute |
| command | string | No* | Shell command to execute (uses $SHELL or /bin/sh) |
| timeout | number | No | Maximum runtime in seconds before termination |
| concurrency | object | No | Concurrency settings |
| concurrency.max | number | No | Maximum instances (default: 1) |
| concurrency.allow_overlap | boolean | No | Allow task to overlap itself (default: false) |
| env | object | No | Environment variables to pass to task |
| retry | object | No | Retry settings for failed tasks |
| retry.attempts | number | No | Number of retry attempts |
| retry.backoff | string | No | Backoff strategy ("fixed" or "exponential") |
| retry.delay | number | No | Delay in seconds between retries |\* Either
file or command is required, but not both.Common Use Cases
- Recurring database maintenance: Schedule database cleanup, backups, or migrations
- Application monitoring: Log metrics, check service health, or generate reports
- Data processing: Schedule batch processing of data at regular intervals
- Service coordination: Trigger API calls or service interactions on a schedule
Developing with Captain
For developers who want to modify or extend Captain:
`bash
Clone the repository
git clone
cd captainInstall dependencies
npm installRun in development mode
npm run devRun tests
npm test
``ISC