Traits

The Traits module provides type-based polymorphism for Kit. Traits define shared behavior that types can implement, enabling generic programming and consistent interfaces across different types.

# Use trait methods on built-in types
println (Int.eq? 5 5)        # => true
println (Int.compare 3 7)    # => Less
println (Int.show 42)        # => "42"

Overview

Kit's trait system consists of two parts:

• Trait definitions — declare the methods a type must implement
• Trait implementations — provide the actual methods for specific types

Built-in types like Int, Float, String, and Bool come with pre-implemented trait methods that you can use directly via the TypeName.method pattern.

Defining Traits

Define a trait using the trait keyword with a name and type parameter:

# Trait with one required method
trait Eq a
  eq?: (a, a) -> Bool

Traits declare required methods with a type signature (e.g., eq?: (a, a) -> Bool). Types implementing the trait must provide implementations for all required methods.

Supertraits

A trait can require other traits using the requires keyword:

# Ord requires Eq - any type implementing Ord must also implement Eq
trait Ord a requires Eq
  compare: (a, a) -> Ordering

Implementing Traits

Implement a trait for a type using extend with with:

# Implement Eq for Int
extend Int with Eq
  eq? = fn(a, b) => a == b

# Implement Ord for Int (requires Eq already implemented)
extend Int with Ord
  compare = fn(a, b) =>
    if a < b then Less
    else if a > b then Greater
    else Equal

Implementations may also use braces, for example extend Int with Eq { eq? = fn(a, b) => a == b }. Kit rejects a second implementation of the same trait for the same type because its methods would overlap.

Method Dispatch

You can call a trait method with a type-qualified name, or call it bare when the first argument has a statically known implementing type. For example, Dog.describe dog and describe dog select the same implementation. A real local binding with the same name takes precedence over bare trait dispatch.

Conditional Implementations

For parameterized types, use where to require trait bounds on type parameters:

# A list is Eq if its elements are Eq
extend List a with Eq where Eq a
  eq? = fn(xs, ys) =>
    match (xs, ys)
    | ([], []) -> true
    | ([x | xt], [y | yt]) -> eq? x y && eq? xt yt
    | _ -> false

Standard Traits

The Traits module defines these core traits:

# Default values for built-in types
# Int.default    = 0
# Float.default  = 0.0
# String.default = ""
# Bool.default   = false

# For primitive types, clone is identity
# For compound types, clone creates a deep copy
original = [1, 2, 3]
copy = clone original

# Implement Hash for a custom type
extend MyType with Hash
  hash = fn(x) => hash(x.id)

# Then use in Map/Set
my-map = Map.empty : Map MyType String

x = 42
println (show x)   # => "42"
println (debug x)  # => "Int(42)"

name = "Alice"
println (show name)   # => "Alice"
println (debug name)  # => "String(\"Alice\")"

type DbError =
  | ConnectionFailed String
  | QueryFailed String Int
  | Timeout

extend DbError with Error
  message = fn(e) => match e
  | ConnectionFailed msg -> msg
  | QueryFailed msg _ -> msg
  | Timeout -> "Database operation timed out"

  kind = fn(e) => match e
  | ConnectionFailed _ -> :connection-failed
  | QueryFailed _ _ -> :query-failed
  | Timeout -> :timeout

# Works with both eager and lazy values
compute = fn(x) => Int.force(x) * 2
compute(5)              # => 10
compute(lazy(fn => 5)) # => 10 (after forcing)

Serialization Traits

These traits provide standard interfaces for encoding and decoding values to various formats. Each format package defines its own marker type.

# In kit-json package
type Json = Json

extend User with StringEncode Json
  encode = fn(user) =>
    "{\"name\": \"${user.name}\", \"age\": ${user.age}}"

# Usage
Json.encode(user)  # => {"name": "Alice", "age": 30}

extend User with StringDecode Json JsonError
  decode = fn(s) =>
    # parsing logic...
    Ok {name: "...", age: 0}

# Usage
Json.decode(str) : Result User JsonError

Standard Types

The Traits module also defines several useful algebraic data types.

match Int.compare a b
| Less -> println "a < b"
| Equal -> println "a == b"
| Greater -> println "a > b"

Ordering Helper Functions

# Ordering predicates
println (Ordering.is-less? Less)      # => true
println (Ordering.is-equal? Equal)    # => true

# Chain comparisons (compare by x first, then by y)
compare-points = fn(p1, p2) =>
  Ordering.then
    (Int.compare p1.x p2.x)
    (Int.compare p1.y p2.y)

# Either can represent alternative types
parse-id : String -> Either String Int
parse-id = fn(s) =>
  match Int.parse s
  | Some n -> Right n
  | None -> Left s  # Keep as string if not a number

match parse-id "123"
| Left s -> println "String ID: ${s}"
| Right n -> println "Numeric ID: ${n}"

Patch Helper Functions

Patch Example

# Define a patch type for updating users
type UserPatch = {
  name: Patch String,
  email: Patch String,
  age: Patch Int
}

# Apply patch to an existing user
apply-user-patch = fn(user, patch) =>
  name = apply-patch (Some user.name) patch.name |>> Option.unwrap-or user.name
  email = apply-patch (Some user.email) patch.email |>> Option.unwrap-or user.email
  age = apply-patch (Some user.age) patch.age |>> Option.unwrap-or user.age
  {name: name, email: email, age: age}

# Example: Update only the email
user = {name: "Alice", email: "old@example.com", age: 30}
patch = {name: Unchanged, email: Assign "new@example.com", age: Unchanged}
updated = apply-user-patch user patch
# => {name: "Alice", email: "new@example.com", age: 30}

Patch implements Eq, Ord, Show, Debug, Clone, Default, and Hash when its type parameter does.

Utility Functions

The Traits module provides these utility functions that work with the Ord trait:

# min and max
println (min 3 7)           # => 3
println (max 3 7)           # => 7

# clamp restricts a value to [low, high]
println (clamp 5 1 10)      # => 5 (within range)
println (clamp -5 1 10)     # => 1 (below range)
println (clamp 15 1 10)     # => 10 (above range)

Built-in Type Methods

Kit's built-in types have pre-implemented trait methods available via the TypeName.method? pattern. Boolean-returning methods use the ? suffix convention.

Examples

# Equality
println (Int.eq? 5 5)           # => true
println (String.eq? "a" "b")    # => false

# Ordering
println (Int.lt? 3 7)           # => true
println (Float.compare 3.14 2.71)  # => Greater

# Use compare result in pattern matching
match Int.compare 10 20
| Less -> println "10 < 20"
| Equal -> println "10 == 20"
| Greater -> println "10 > 20"
# => 10 < 20

# String conversion
println (Int.show 42)          # => "42"
println (Bool.show true)       # => "true"

Traits vs Protocols

Kit offers two ways to add polymorphic behavior to types: Traits and Protocols. Understanding when to use each helps you write cleaner code.

When to Use Traits

• Reusable abstractions — When multiple types share a common interface (e.g., all comparable types implement Ord)
• Supertraits — When one capability depends on another (e.g., Ord requires Eq)
• Default implementations — When you can derive methods from others (e.g., ne? from eq?)
• Conditional implementations — When a container's behavior depends on its element type (e.g., List a is Eq if a is Eq)
• Library design — When defining interfaces that others will implement

When to Use Protocols

• Quick customization — When you just need to add eq? or to-str to a single type
• Operator overloading — When you want == or < to work with your type
• Printing and display — When you need custom output with println
• Simple cases — When you don't need supertraits or conditional implementations

Protocol Example

type Point = Point(Int, Int)

# Define protocol functions for Point
Point.eq? = fn(p1, p2) =>
  Point(x1, y1) = p1
  Point(x2, y2) = p2
  x1 == x2 && y1 == y2

Point.to-str = fn(p) =>
  Point(x, y) = p
  "Point(${x}, ${y})"

# Kit uses your protocol functions automatically
p1 = Point(1, 2)
p2 = Point(1, 2)
println (p1 == p2)  # => true (uses Point.eq?)
println p1          # => Point(1, 2) (uses Point.to-str)

See Protocols in the Language Guide for more details.