Language Conversion Guide

Comprehensive patterns and strategies for converting code between programming languages.

Quick Navigation

| Resource | Purpose | | -------------------------------------------------------- | ------------------------------------- | | FORMS.md | Templates, checklists, decision trees | | tables/quick-reference.md | Condensed lookup tables |

Examples

| File | Content | | ---------------------------------------------------------------- | -------------------------------------------- | | examples/idiom-translation.md | Null handling, collections, pattern matching | | examples/error-handling.md | Exception→Result, error hierarchies | | examples/concurrency.md | Promise/Future, parallel execution | | examples/metaprogramming.md | Decorators, macros, DI patterns | | examples/serialization.md | JSON, validation, polymorphic types |

Reference Guides

| File | Content | | ------------------------------------------------------------------------------ | ---------------------------------- | | reference/difficulty-matrix.md | Conversion difficulty ratings | | reference/type-system-mapping.md | Primitives, composites, generics | | reference/error-handling.md | Error models, let-it-crash | | reference/concurrency.md | Async models, channels, goroutines | | reference/dev-workflow-repl.md | 9th pillar, REPL patterns | | reference/memory-ownership.md | GC→ownership, borrowing | | reference/evaluation-strategy.md | Lazy vs eager patterns | | reference/metaprogramming.md | Macros, reflection, code gen | | reference/type-system-translation.md | Static↔dynamic, inference | | reference/paradigm-translation.md | OOP→FP, FP→FP | | reference/serialization.md | Library mapping, attributes | | reference/typescript-patterns.md | Type guards, mapped types | | reference/hkt-type-classes.md | HKTs, Functor, Monad | | reference/async-patterns.md | Cancellation, streams | | reference/dependency-management.md | Package ecosystems | | reference/performance.md | Pitfalls, benchmarking |

Gotchas

| File | Content | | ---------------------------------------------------------------------- | ------------------------------------ | | reference/gotchas/by-family.md | OOP→FP, Dynamic→Static, GC→Ownership | | reference/gotchas/by-language.md | Python→Rust, TypeScript→Rust, etc. |

When to Use This Skill

Converting code from one language to another
Planning a language migration
Understanding conversion challenges between languages
Looking up type mappings or idiom translations
Referencing error handling, concurrency, or async patterns across languages
Learning about gotchas when converting between specific language families

This Skill Does NOT Cover

Creating new conversion skills (see meta-convert-dev)
Language tutorials (see lang-*-dev skills)
Runtime interop/FFI (see language-specific interop skills)

Related Skills

meta-convert-dev - For creating new convert-X-Y skills
convert-* skills - Language-pair specific conversion skills

Core Conversion Methodology

The APTV Workflow

Every conversion follows: Analyze → Plan → Transform → Validate

┌─────────────────────────────────────────────────────────────┐
│                    CONVERSION WORKFLOW                       │
├─────────────────────────────────────────────────────────────┤
│  1. ANALYZE    │  Understand source code structure          │
│                │  • Parse and identify components            │
│                │  • Map dependencies                         │
│                │  • Identify language-specific patterns      │
├─────────────────────────────────────────────────────────────┤
│  2. PLAN       │  Design the target architecture            │
│                │  • Create type mapping table                │
│                │  • Identify idiom translations              │
│                │  • Plan module/package structure            │
├─────────────────────────────────────────────────────────────┤
│  3. TRANSFORM  │  Convert code systematically               │
│                │  • Types and interfaces first               │
│                │  • Core logic second                        │
│                │  • Adopt target idioms (don't transliterate)│
├─────────────────────────────────────────────────────────────┤
│  4. VALIDATE   │  Verify functional equivalence             │
│                │  • Run original tests against new code      │
│                │  • Property-based testing for edge cases    │
│                │  • Performance comparison if relevant       │
└─────────────────────────────────────────────────────────────┘

See also: FORMS.md for APTV phase checklists

Analyze Phase

Before writing any target code:

Parse the source - Understand structure, not just syntax
Identify components:
- Types/interfaces/classes
- Functions/methods
- Module boundaries
- External dependencies
Note language-specific features:
- Generics usage
- Error handling patterns
- Async patterns
- Memory management approach

Plan Phase

Create explicit mappings before transforming. Use the templates in FORMS.md:

## Type Mapping Table

| Source (TypeScript) | Target (Rust)      | Notes             |
| ------------------- | ------------------ | ----------------- |
| `string`            | `String` / `&str`  | Owned vs borrowed |
| `number`            | `i32` / `f64`      | Specify precision |
| `T[]`               | `Vec<T>`           | Owned collection  |
| `T \| null`         | `Option<T>`        | Nullable handling |
| `Promise<T>`        | `Future<Output=T>` | Async handling    |

See also: reference/type-system-mapping.md for complete mappings

Transform Phase

Golden Rule: Adopt target idioms, don't write "Source code in Target syntax"

// Source: TypeScript
function findUser(id: string): User | null {
  const user = users.find((u) => u.id === id);
  return user || null;
}

// BAD: Transliterated (TypeScript in Rust clothing)
fn find_user(id: String) -> Option<User> {
    let user = users.iter().find(|u| u.id == id);
    match user {
        Some(u) => Some(u.clone()),
        None => None,
    }
}

// GOOD: Idiomatic Rust
fn find_user(id: &str) -> Option<&User> {
    users.iter().find(|u| u.id == id)
}

See also: examples/idiom-translation.md for more patterns

Validate Phase

Functional equivalence: Same inputs → same outputs
Edge case coverage: Property-based tests
Error behavior: Same error conditions trigger appropriately
Performance baseline: Comparable or better performance

See also: FORMS.md for testing strategy checklist

The 8 Pillars of Conversion

Every comprehensive conversion addresses these domains:

| Pillar | What to Convert | Reference | | -------------------------- | ------------------------------ | -------------------------------------------------------------------------- | | 1. Module System | Imports, exports, packages | reference/type-system-mapping.md | | 2. Error Handling | Exceptions, Results, panics | reference/error-handling.md | | 3. Concurrency | Async, threads, channels | reference/concurrency.md | | 4. Metaprogramming | Decorators, macros, reflection | reference/metaprogramming.md | | 5. Zero/Default Values | Nullability, defaults | reference/type-system-mapping.md | | 6. Serialization | JSON, validation, schemas | reference/serialization.md | | 7. Build System | Package managers, dependencies | reference/dependency-management.md | | 8. Testing | Test frameworks, assertions | FORMS.md |

The 9th Pillar: Dev Workflow

For REPL-centric languages (Clojure, Elixir, Haskell), add:

| Source | Target | Consideration | | --------------- | --------- | ------------------------- | | REPL-centric | Compiled | Document workflow changes | | Hot reload | Recompile | Faster incremental builds | | Live inspection | Debugging | Logger, debugger setup |

See also: reference/dev-workflow-repl.md

Quick Reference Tables

Type System Comparison

| Language | Typing | Null Safety | Generics | | ---------- | ----------- | ------------------- | ---------- | | TypeScript | Static | Optional (strict) | Full | | Python | Dynamic | None (runtime) | Type hints | | Rust | Static | Enforced (Option) | Full | | Go | Static | Nil pointers | 1.18+ | | Elixir | Dynamic | nil atoms | None | | Haskell | Static (HM) | Enforced (Maybe) | Full + HKT |

See also: tables/quick-reference.md for complete tables

Error Model Comparison

| Language | Model | Propagation | | ---------- | ------------- | -------------------------- | | TypeScript | Exceptions | throw / try-catch | | Python | Exceptions | raise / try-except | | Rust | Result type | ? operator | | Go | Error returns | if err != nil | | Elixir | Pattern match | {:ok, _} / {:error, _} | | Haskell | Either/Maybe | Monadic bind |

See also: reference/error-handling.md

Concurrency Model Comparison

| Language | Model | Primitives | | ---------- | ---------- | --------------------- | | TypeScript | Event loop | Promises, async/await | | Python | Event loop | asyncio, await | | Rust | Futures | tokio, async/await | | Go | CSP | Goroutines, channels | | Elixir | Actors | Processes, GenServer | | Erlang | Actors | Processes, mailboxes |

See also: reference/concurrency.md

Common Conversion Patterns

Null Handling

| Source | Target Rust | Pattern | | ---------------- | ---------------------- | ----------------- | | x ?? default | x.unwrap_or(default) | Default value | | x?.prop | x.map(\|v\| v.prop) | Optional chaining | | if (x != null) | if let Some(v) = x | Null check |

See also: examples/idiom-translation.md

Error Propagation

| Source | Target | Pattern | | ---------------------- | ---------------------------------------------- | ----------------- | | throw new Error(msg) | return Err(Error::new(msg)) | Throw → Result | | try { } catch { } | match result { Ok(_) => ..., Err(_) => ... } | Try/catch → match | | Rethrow | ? operator | Propagate error |

See also: examples/error-handling.md

Collection Operations

| Source (JS/TS) | Target (Rust) | Notes | | ------------------ | ----------------------- | ------------------- | | .map(f) | .iter().map(f) | Lazy in Rust | | .filter(f) | .iter().filter(f) | Lazy in Rust | | .reduce(f, init) | .iter().fold(init, f) | Different arg order | | .find(f) | .iter().find(f) | Returns Option |

See also: tables/quick-reference.md

Decision Trees

When to Clone vs Borrow

Is the data needed after the function returns?
├─ NO → Borrow (&T)
└─ YES → Does caller need to keep using it?
         ├─ NO → Move (T)
         └─ YES → Clone (.clone())

See also: FORMS.md for complete decision trees

GC → Ownership Strategy

Is this data shared across components?
├─ YES → Consider Arc<T> or Rc<T>
└─ NO → Single owner, use moves

Is this data mutated by multiple parts?
├─ YES → Arc<Mutex<T>> or channels
└─ NO → Immutable borrows (&T)

See also: reference/memory-ownership.md

Common Pitfalls

| Pitfall | Wrong | Right | | ------------------------- | ------------------------------- | --------------------- | | Transliteration | Write TypeScript in Rust syntax | Write idiomatic Rust | | Ignoring idioms | Port class hierarchies to Rust | Use enums and traits | | 1:1 mapping | Every function maps exactly | Restructure as needed | | Preserve inefficiency | Port inefficient algorithms | Optimize for target | | Ignore conventions | camelCase in Python | snake_case (Python) |

See also: reference/gotchas/by-family.md

Testing Conversions

Testing Pyramid

         ┌───────────────┐
         │  Integration  │  Same API behavior
         └───────────────┘
    ┌─────────────────────────┐
    │    Property-Based       │  Invariants hold
    └─────────────────────────┘
 ┌───────────────────────────────────┐
 │           Unit Tests              │  Logic matches
 └───────────────────────────────────┘
┌─────────────────────────────────────────┐
│        Input/Output Comparison          │  Golden tests
└─────────────────────────────────────────┘

Golden Testing

Generate test cases from original implementation
Save as JSON fixtures
Run converted code against same inputs
Compare outputs

See also: FORMS.md for testing checklist

Language-Specific Quick Links

Converting FROM

| Source | Key Gotchas | Reference | | ---------- | ---------------------------- | ----------------------------------------------------------------------------------- | | Python | Duck typing, None everywhere | reference/gotchas/by-language.md | | TypeScript | Optional properties, any | reference/typescript-patterns.md | | Go | Zero values, nil | reference/gotchas/by-language.md | | Java | Null, checked exceptions | reference/gotchas/by-language.md | | Haskell | HKTs, laziness | reference/hkt-type-classes.md | | Elixir | Pattern matching, processes | reference/gotchas/by-language.md |

Converting TO

| Target | Key Considerations | Reference | | ------ | --------------------------- | ------------------------------------------------------------------------------ | | Rust | Ownership, borrowing | reference/memory-ownership.md | | Go | Simplicity, explicit errors | reference/error-handling.md | | Python | Dynamic typing | reference/type-system-translation.md | | Elixir | Functional, BEAM | reference/paradigm-translation.md |

References

Related Skills

meta-convert-dev - For creating new convert-X-Y skills
convert-typescript-rust - TypeScript → Rust conversion
convert-python-rust - Python → Rust conversion
convert-golang-rust - Go → Rust conversion

Language Skills

For language-specific fundamentals (not conversion):

lang-typescript-dev - TypeScript development patterns
lang-python-dev - Python development patterns
lang-rust-dev - Rust development patterns
lang-elixir-dev - Elixir development patterns

meta-convert-guide

Language Conversion Guide

Quick Navigation

Examples

Reference Guides

Gotchas

When to Use This Skill

This Skill Does NOT Cover

Related Skills

Core Conversion Methodology

The APTV Workflow

Analyze Phase

Plan Phase

Transform Phase

Validate Phase

The 8 Pillars of Conversion

The 9th Pillar: Dev Workflow

Quick Reference Tables

Type System Comparison

Error Model Comparison

Concurrency Model Comparison

Common Conversion Patterns

Null Handling

Error Propagation

Collection Operations

Decision Trees

When to Clone vs Borrow

GC → Ownership Strategy

Common Pitfalls

Testing Conversions

Testing Pyramid

Golden Testing

Language-Specific Quick Links

Converting FROM

Converting TO

References

Related Skills

Language Skills