Crystal Type Inference: Static Safety Without Constant Annotations

What Crystal's Type Inference Actually Does

Crystal's compiler uses a Hindley-Milner inspired type system. That means it can deduce the type of a variable from how you assign and use it, without you writing the type everywhere. This is global type inference: the compiler looks across your code, not just one line at a time.

When you write count = 0, the compiler marks count as Int32. If you later try count = "zero", compilation stops because the inferred type does not match.

Method Signatures Are the Contract Boundary

Local variables are inferred, but method parameters usually are not. You write the types in the signature so the compiler knows the contract before it checks the body.

def greet(name : String)
  "Hello, #{name}"
end

Without : String, the compiler cannot assume what name supports. The annotation tells Crystal and other developers what the method accepts.

Worked Example: Generic Methods and Union Types

Crystal can generate a specialized version of a method for each type you pass to it. This is generic programming, and the type is determined by the arguments at compile time.

def first_element(array : Array(T)) where T
  array[0]
end

numbers = [1, 2, 3]
words = ["apple", "banana"]

puts first_element(numbers)
puts first_element(words)

Here T is a type variable. The compiler infers Int32 for the first call and String for the second, producing separate specialized code for each.

A union type lets a variable hold one of several specific types. The vertical bar means "or".

def format(value : Int32 | String)
  case value
  when Int32 then "number: #{value}"
  when String then "text: #{value}"
  end
end

The compiler checks every branch, so you cannot forget a case and still compile.

Where Inference Gets Complicated

Deeply nested type inference can slow compile times in very large projects. Type mismatch errors can also appear far from the actual source because the inference engine propagates types through calls. When an error points to a line that looks correct, trace the value back to where it was first assigned or passed into a method.

How to Verify Your Types

Run the compiler from your project root:

crystal build src/type_inference.cr

Where: terminal in the project directory. Permissions: none required. Placeholder: replace src/type_inference.cr with your file path. Expected check: a zero exit code and a binary named type_inference. If there is a mismatch, Crystal prints the file, line, and column. Risk: compilation fails; no system state is changed, so there is nothing to roll back.

Practical check: intentionally reassign an inferred variable to a different type:

count = 0
count = "zero"

The compiler should reject the second line because count was inferred as Int32.

Trade-Offs and Limitations

• Inference keeps code concise, but over-reliance in complex public APIs can make it harder for teammates to reason about without IDE support.
• Explicit annotations on method signatures act as documentation and reduce the distance between a mistake and its compiler error.
• Union types add flexibility, but every branch must be handled or the code will not compile.

Actionable Closing

Start by letting the compiler infer local variables. Add explicit types to method signatures, especially on public methods. Use union types when a value genuinely needs more than one type. Run crystal build early and often so errors surface near the change that caused them.