coffee-to-ts

A CLI tool that converts CoffeeScript files to TypeScript with intelligent type inference.

Features

• Smart Conversion: Converts CoffeeScript to TypeScript while preserving functionality
• Intelligent Type Inference: Automatically infers types from code patterns and usage
• Dependency Analysis: Converts files in topological order, respecting dependencies
• CLI & API: Use as a command-line tool or integrate programmatically
• Conservative Approach: Uses any when uncertain, allowing incremental type refinement
• Comment Preservation: Preserves all comments by default

Installation

npm install -g coffee-to-ts

Or use locally in your project:

npm install --save-dev coffee-to-ts

Quick Start

Convert a single file:

coffee2ts convert input.coffee

Convert with dependencies:

coffee2ts convert app.coffee --with-deps

Convert a directory:

coffee2ts convert src/ dist/

Usage

CLI Commands

Convert Command

# Convert single file
coffee2ts convert input.coffee output.ts

# Convert single file (automatic output name)
coffee2ts convert input.coffee

# Convert directory
coffee2ts convert src/ dist/

# Convert directory in place
coffee2ts convert src/

# Convert with dependencies (topological order)
coffee2ts convert app.coffee --with-deps

# Show dependency graph
coffee2ts convert app.coffee --show-graph

# Convert with limit (only N files, closest to leaves first)
coffee2ts convert app.coffee --with-deps --limit 5

# Skip first N files in processing order
coffee2ts convert app.coffee --with-deps --skip 3

# Combine skip and limit
coffee2ts convert app.coffee --with-deps --skip 3 --limit 5

# Use output directory option
coffee2ts convert src/ -o dist/

Status Command

# Check conversion status for a file and its dependencies
coffee2ts status app.coffee

The status command shows:

• Total files in dependency tree
• Converted vs unconverted files
• Circular dependency warnings
• Dependency tree visualization with conversion status
• Files that need conversion sorted by dependency count

CLI Options

• --with-deps - Convert dependencies in topological order
• --show-graph - Display dependency graph before conversion
• --limit <number> - Convert only N files (requires --with-deps)
• --skip <number> - Skip first N files in processing order (requires --with-deps)
• -o, --output <dir> - Specify output directory

Programmatic API

import { convertCoffeeScriptToTypeScript } from 'coffee-to-ts';

// Basic conversion
const result = await convertCoffeeScriptToTypeScript(coffeeCode);

console.log(result.typescript);
console.log(result.metadata.typesAdded); // Number of types inferred

Dependency Processing

When using --with-deps, coffee-to-ts:

1. Analyzes all dependencies recursively
2. Builds a dependency graph
3. Converts files in topological order (leaves first)
4. Skips already-converted files (where .ts file exists)
5. Supports --limit to convert only N files with fewest dependencies
6. Supports --skip to skip the first N files in processing order

Supported CoffeeScript Features

coffee-to-ts handles all major CoffeeScript features:

• Functions (arrow, named, anonymous)
• Classes (basic, inheritance, static members)
• Comprehensions (list, object, nested)
• Existence checks (?, ?.)
• Destructuring (arrays, objects)
• Splats (rest parameters, spread)
• String interpolation
• Operators (is, and, or, not, in, of)
• Ranges (inclusive, exclusive)
• Loops (for...in, for...of, while)
• Conditionals (if, unless, postfix)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Resources

• CoffeeScript Documentation
• TypeScript Documentation
• Decaffeinate Project