Kairo Type System: Scalars, Collections, and Domain Types

Kairo’s type system is built around one central distinction: values model facts, objects model participants. Everything else, scalars, collections, nullability, generics, follows from that idea.

Values vs. objects

value

Immutable facts with no identity. Two values with equal fields are the same value. Used for IDs, amounts, dates, coordinates.

object

Identity-bearing participants. Two objects with equal fields are still distinct. Used for entities, workflows, stateful concepts.

public value Money {
    amount: Decimal
    currency: Text
}

public object Customer {
    public id: CustomerId
    public var name: Text

    public init(id: CustomerId, name: Text) {
        this.id = id
        this.name = name
    }
}

A value’s members must be value-like. You cannot store an object inside a value. This keeps identity-bearing state from leaking into fact-shaped types.

Scalar types

Type	Range	Notes
`Bool`	`true` / `false`	No truthy/falsy conversions
`Int32`	32-bit signed integer
`Int64`	64-bit signed integer	Default for integer literals
`Decimal`	Exact decimal	Default for fractional literals
`Float64`	64-bit IEEE float	Requires explicit typing
`Text`	Unicode text	Used in place of `String`

let count: Int64 = 100
let price: Decimal = 125.50
let label: Text = "Ready"
let active: Bool = true

Fractional literals default to Decimal because business math should be exact. Reach for Float64 only when you know you need IEEE semantics.

Collections

Collections are immutable in v0.1. A mutable collection model is deferred.

List<T>

Immutable ordered collection.

Set<T>

Immutable unique collection.

Map<K, V>

Immutable key-value collection.

public value CustomerPage {
    ids: List<CustomerId>
}

public value CustomerTags {
    tags: Set<Text>
}

public value ExchangeRates {
    rates: Map<Text, Decimal>
}

A collection is value-like only when its element (or key and value) types are value-like. Map<CustomerId, Customer> is not value-like if Customer is an object.

Nullability

Nullability is part of the type, not a hidden runtime state. Customer and Customer? are different types.

public func findCustomer(id: CustomerId): Customer? {
    return null
}

Rules:

null can only be assigned where the target type ends in ?.
Nested nullables like T?? are not part of v0.1.
T? in a value member is only allowed when T is value-like.

Domain types

Kairo encourages naming your domain concepts as small value types instead of primitives. This makes signatures self-documenting.

public value CustomerId {
    value: Text
}

public value EmailAddress {
    value: Text
}

public func lookup(id: CustomerId): Customer? {
    return null
}

Result and outcomes

Result<T, E> is a value-like type from the Kairo Core prelude for representing expected outcomes. See Error Handling for the full model.

public func createEmail(value: Text): Result<EmailAddress, EmailFailure> {
    if value == "" {
        return Result.failure(EmailFailure.Empty)
    }
    return Result.success(EmailAddress { value: value })
}

Contracts and generics

Contracts declare capabilities. Generic type parameters let types and contracts work over other types.

public contract Displayable {
    func display(): Text
}

public contract Formatter<T: Displayable> {
    func format(value: T): Text
}

See Declarations reference for the full syntax.

Next steps

Functions

Free functions, methods, async, and calling conventions.

Error handling

How Result<T, E> and faults fit together.

Get Started

Language

Packages & Modules

Toolchain

Ecosystem

Kairo Type System: Scalars, Collections, and Domain Types

Values vs. objects

value

object

Scalar types

Collections

List<T>

Set<T>

Map<K, V>

Nullability

Domain types

Result and outcomes

Contracts and generics

Next steps

Functions

Error handling

​Values vs. objects

value

object

​Scalar types

​Collections

List<T>

Set<T>

Map<K, V>

​Nullability

​Domain types

​Result and outcomes

​Contracts and generics

​Next steps

Functions

Error handling

Values vs. objects

Scalar types

Collections

Nullability

Domain types

Result and outcomes

Contracts and generics

Next steps