Koine | Blog

Modeling money: value objects and invariants in Koine

Wed, 17 Jun 2026 00:00:00 GMT

Money is the example everyone reaches for when explaining value objects, and for good reason. It’s defined entirely by its values (€10 is €10), it’s immutable, and it carries a rule that must always hold: an amount can’t be negative. That makes it the perfect first thing to model in Koine.

A value object is its values

Here’s Money and the smart enum it depends on:

context Billing {

  enum Currency(symbol: String, decimals: Int) {
    EUR("€", 2)
    USD("$", 2)
    GBP("£", 2)
  }

  value Money {
    amount:   Decimal
    currency: Currency
    invariant amount >= 0   "a monetary amount cannot be negative"
  }
}

Three things are happening:

value Money declares a value object. Its identity is the tuple of its fields — two Money instances with the same amount and currency are equal, full stop.
Currency is a smart enum whose members carry constant data. EUR isn’t just a name; it knows its symbol and how many decimals it has.
The invariant states a rule in domain language, with the message a user will see if it’s violated.

The C# you get back

koine build emits Billing/ValueObjects/Money.cs (output is nested by category — value objects go under ValueObjects/, enums under Enums/). The shape is the same one you’d write by hand — a sealed class, a validating constructor, by-value equality:

public sealed class Money : ValueObject
{
    public decimal Amount { get; }
    public Currency Currency { get; }

    public Money(decimal amount, Currency currency)
    {
        if (amount < 0)
        {
            throw new DomainInvariantViolationException(
                type: nameof(Money),
                rule: "a monetary amount cannot be negative");
        }

        Amount = amount;
        Currency = currency;
    }

    public override string ToString()
        => $"Money {{ Amount = {Amount}, Currency = {Currency} }}";

    protected override IEnumerable<object?> GetEqualityComponents()
    {
        yield return Amount;
        yield return Currency;
    }
}

The guard is inverted: the emitter negates amount >= 0 to amount < 0 and always wraps it in braces — the constructor fails fast with the literal message you wrote in the model.

The Currency field type is the smart enum generated alongside Money into Billing/Enums/Currency.cs. Here’s a representative excerpt:

/// <summary>A type-safe smart enum: static instances with value equality.</summary>
public sealed class Currency : IEquatable<Currency>
{
    public static readonly Currency EUR = new("EUR", 0, "€", 2);
    public static readonly Currency USD = new("USD", 1, "$", 2);
    public static readonly Currency GBP = new("GBP", 2, "£", 2);

    public string Name { get; }
    public int Value { get; }
    public string Symbol { get; }
    public int Decimals { get; }

    private Currency(string name, int value, string symbol, int decimals)
    {
        Name = name;
        Value = value;
        Symbol = symbol;
        Decimals = decimals;
    }

    public static IReadOnlyList<Currency> All { get; } = new[] { EUR, USD, GBP };

    public static Currency FromName(string name)
        => All.FirstOrDefault(e => e.Name == name)
            ?? throw new ArgumentOutOfRangeException(nameof(name), $"No Currency with name '{name}'.");

    // … TryFromName / FromValue / TryFromValue …

    public TResult Match<TResult>(
        Func<TResult> eUR,
        Func<TResult> uSD,
        Func<TResult> gBP)
        => Value switch
        {
            0 => eUR(),
            1 => uSD(),
            2 => gBP(),
            _ => throw new InvalidOperationException($"Unhandled Currency '{Name}'.")
        };

    // … Switch / ToString / Equals / GetHashCode / == / != …
}

EUR isn’t just a name: it carries Symbol = "€" and Decimals = 2. The Match signature is exhaustive — the compiler forces you to handle every member. This is the class that Money.Currency references; Money carries a Currency reference, not a raw string or integer.

The key move is where the invariant lands: it’s a guard at the top of the constructor, before any field is assigned. There is no way to construct a negative Money. The object is valid by the time it exists, or it doesn’t exist — the rule isn’t a method you have to remember to call, it’s a property of the type. Equality comes from the ValueObject base (a small emitted marker, not a NuGet package): GetEqualityComponents lists the fields that define identity, and the base supplies Equals, GetHashCode, and ==/!=.

Derived fields: computed, not stored

Often a value object exposes something computed from its other fields. Say you want a normalized SKU:

value Sku {
  code:       String
  normalized: String = code.trim.upper
  invariant code.trim.length > 0               "a SKU cannot be blank"
  invariant code matches /^[A-Z]{3}-[0-9]{4}$/  "SKU must look like ABC-1234"
}

A field with an = expression that references other fields is derived. It does not become a constructor parameter — you can’t pass it in — it becomes a get-only computed property:

public string Normalized => Code.Trim().ToUpperInvariant();

That distinction is the whole point: code is input you supply; normalized is a consequence the model computes. And the second invariant — matches /…/ — compiles straight to Regex.IsMatch, so a malformed SKU is rejected at construction time just like a negative amount.

Why this is the part worth getting right

Value objects are where a domain model earns its keep. Push the rules down into the type and the rest of the system gets simpler for free: an application service that accepts a Money never has to re-check that it’s non-negative, because a negative Money is unrepresentable. Koine makes stating those rules cheap — one invariant line — and turns them into guard clauses you can read and trust.

From here, value objects in the reference covers quantities (a Decimal plus a unit, with unit-checked arithmetic), Range<T> intervals, and more derived-field patterns. Or open Koine Studio, tweak the Money invariant, and watch the guard clause change as you type.

One model, many targets: how Koine stays language-agnostic

Wed, 17 Jun 2026 00:00:00 GMT

A domain model isn’t a C# thing. “A Money is an amount and a currency, and the amount can’t be negative” is true regardless of the language you ship it in. Koine takes that seriously: the parser and the semantic model are kept strictly target-agnostic, and no C# concept is allowed to leak into them. The payoff is that adding a language is writing a new emitter, not rewriting the compiler — and you can prove it by flipping one flag.

The same model, a different flag

Here’s a Billing context with a smart enum and a value object:

context Billing {

  enum Currency(symbol: String, decimals: Int) {
    EUR("€", 2)
    USD("$", 2)
    GBP("£", 2)
  }

  value Money {
    amount:   Decimal
    currency: Currency
    invariant amount >= 0   "a monetary amount cannot be negative"
  }
}

Build it for C#:

koine build billing.koi --target csharp --out ./generated

and Money lands at Billing/ValueObjects/Money.cs:

public sealed class Money : ValueObject
{
    public decimal Amount { get; }
    public Currency Currency { get; }

    public Money(decimal amount, Currency currency)
    {
        if (amount < 0)
        {
            throw new DomainInvariantViolationException(
                type: nameof(Money),
                rule: "a monetary amount cannot be negative");
        }

        Amount = amount;
        Currency = currency;
    }

    public override string ToString()
        => $"Money {{ Amount = {Amount}, Currency = {Currency} }}";

    protected override IEnumerable<object?> GetEqualityComponents()
    {
        yield return Amount;
        yield return Currency;
    }
}

Now change one word — --target typescript — and the same model compiles to Billing/value-objects/Money.ts:

// <auto-generated/>
import { DomainInvariantViolationError, Decimal, ValueObject } from '../../runtime';
import { CurrencyMember } from '../enums/Currency';

export class Money extends ValueObject {
  readonly amount: Decimal;
  readonly currency: CurrencyMember;

  constructor(amount: Decimal, currency: CurrencyMember) {
    super();
    if (!(amount.compareTo(new Decimal('0')) >= 0)) {
      throw new DomainInvariantViolationError('Money', 'a monetary amount cannot be negative');
    }
    this.amount = amount;
    this.currency = currency;
  }

  protected equalityComponents(): readonly unknown[] {
    return [this.amount, this.currency];
  }
}

Same fields, same invariant, same value-equality semantics — expressed idiomatically for each language. The model didn’t change; only the emitter did.

Idiomatic means different, on purpose

A naïve “transpiler” would emit C#-shaped TypeScript. Koine’s emitters instead lean into each language’s conventions, which is why the two outputs aren’t line-for-line translations:

The runtime. C# gets a Koine/Runtime/ folder of marker types (ValueObject, DomainInvariantViolationException, …) emitted only when used. TypeScript gets a single runtime.ts — and because JavaScript’s number is lossy for money, that runtime ships a string-backed Decimal class, so Money.amount is a Decimal, not a number.
The exception. C# throws DomainInvariantViolationException; idiomatic TypeScript throws a DomainInvariantViolationError (the …Error suffix is the JS convention).
The guard. The C# emitter simplifies amount >= 0 to the inverted guard if (amount < 0); the TypeScript emitter keeps the explicit if (!(amount.compareTo(new Decimal('0')) >= 0)), routed through Decimal.compareTo. Same rule, two natural spellings.
The smart enum. In C#, Currency becomes a sealed class : IEquatable<Currency> with static instances. In TypeScript it becomes a CurrencyMember interface plus a const Currency = { … } object and free functions (CurrencyFromName, CurrencyMatch, …) — the shape a TS developer expects. That’s why Money.currency is typed Currency in C# but CurrencyMember in TS.
Even the folders. C# uses Billing/ValueObjects/… and Billing/Enums/…; the TypeScript emitter uses lower-case, kebab-case Billing/value-objects/… and Billing/enums/…, plus a tsconfig.json.

None of these choices live in the model. They live in their respective emitters.

Why the boundary is worth defending

.koi source
  → ANTLR lexer/parser
  → semantic model        ← target-agnostic; knows nothing about C# or TS
  → semantic validator
  → IEmitter              ← C#, TypeScript, Python, PHP, glossary
  → idiomatic source files

Everything above the emitter line is shared. Parsing, name resolution, type checking, and every diagnostic happen once, against a model that has no opinion about output languages. An emitter is just an IEmitter that walks that model and writes text. So a new target inherits all the validation and correctness work for free — it only has to answer “what does this construct look like in my language?”

That discipline is also why Koine Studio can show C#, TypeScript, and a glossary side by side from one model: it’s the same compile, three emitters. C# is the most complete target today; TypeScript is emitting now, Python (Phase 1: tactical core — value objects, smart enums, identity entities, events, and repository protocols, all dependency-free and mypy --strict-clean) and PHP 8.1 (the tactical core and the strategic/CQRS layer — read models, query handler seams, application services/use cases/operations, specifications, policies, context-map ACL translators and integration-event subscriber seams — dependency-free, using typed properties and readonly promoted properties) are available today via the CLI and MCP server. A Rust target ships too (Phase 1: an idiomatic crate — smart constructors returning Result<_, DomainError>, exhaustively-matched enums, repository traits, proved by a cargo check meta-test). Your existing .koi models compile to every target without a single edit — because they never described C# in the first place.

Want to see it live? Open Koine Studio and flip the target dropdown between C# and TypeScript — same model, recompiled on the spot.

Why Koine generates code instead of shipping a framework

Wed, 10 Jun 2026 00:00:00 GMT

There are two ways to help someone write less Domain-Driven Design boilerplate. You can ship a framework — base classes like ValueObject<T>, an AggregateRoot, a Result<T> — that they inherit from and depend on at runtime. Or you can ship a compiler that reads a model and emits the boilerplate as ordinary source code they own.

Koine is firmly in the second camp. This post is about why.

The cost of a base-class framework

A runtime library is the obvious choice, and it has real benefits: it’s familiar, it’s a single NuGet reference, and updates arrive by bumping a version. But it also bakes in costs that compound over the life of a system:

A permanent dependency. Your Money is-a FrameworkValueObject. That coupling never goes away. Upgrading the framework is a domain-wide event; abandoning it is a rewrite.
Magic at runtime. Equality, validation, and serialization often lean on reflection or convention. When something misbehaves, you’re debugging the framework’s internals, not your code.
An abstraction you can’t see. The most important code in your system — the rules that define what a valid Order is — lives behind an inherited member you have to trust rather than read.

None of these are fatal. But for the layer that’s supposed to be the clearest in the whole codebase, they’re exactly the wrong trade.

What a compiler hands you instead

Koine reads a .koi model and writes the C# you would have written by hand. The output has no external dependencies. A small set of marker types (ValueObject, IAggregateRoot, DomainInvariantViolationException, …) is emitted into a Koine/Runtime/ folder only when your model actually uses them — a model with no events never gets IDomainEvent.

So a value object with a couple of invariants and a derived field compiles to exactly this — no base library to inherit, no attributes, no reflection:

// <auto-generated/>
#nullable enable

using System.Collections.Generic;
using System.Text.RegularExpressions;
using Koine.Runtime;

namespace Customers;

public sealed class Email : ValueObject
{
    public string Raw { get; }

    public Email(string raw)
    {
        if (raw.Trim().Length <= 0)
        {
            throw new DomainInvariantViolationException(
                type: nameof(Email),
                rule: "an email cannot be blank");
        }

        if (!Regex.IsMatch(raw, @"^[^@]+@[^@]+\.[^@]+$"))
        {
            throw new DomainInvariantViolationException(
                type: nameof(Email),
                rule: "invalid email address");
        }

        Raw = raw;
    }

    public string Normalized
        => Raw.Trim().ToLowerInvariant();

    public override string ToString()
        => $"Email {{ Raw = {Raw} }}";

    protected override IEnumerable<object?> GetEqualityComponents()
    {
        yield return Raw;
    }
}

You can read every line. You can step through it in a debugger without leaving your own assembly. You can review it in a pull request — and because codegen is deterministic, the same model always produces byte-identical output, so a meaningful diff means a meaningful model change. There’s no hidden behavior because there’s no framework underneath; the marker base class is a small, dependency-free file you can open and read too.

”A green build proves the domain”

The strongest argument for generating code is what it lets you guarantee. Every construct Koine emits is covered two ways in the test suite:

Snapshot tests pin the exact generated text, so an unintended change to the output is caught as a diff.
A Roslyn meta-test compiles the emitted C# in-memory and runs it, asserting that invariants throw, equality works by value, and state machines reject illegal transitions.

When dotnet test is green, the generated C# isn’t just plausible — it’s been compiled and executed. That’s a much stronger claim than a framework can make about the code you write on top of it.

The part that matters most: leverage

Keeping C# out of the semantic model isn’t only architectural tidiness — it’s what makes the output portable. The parser and semantic model don’t know what C# is. The emitter does. Add another emitter and the same model compiles to another language for free: TypeScript, Python, and PHP targets already ship, and Rust is on the roadmap. A framework can’t do that; its base classes are the target.

Generating code costs you a build step. In return you get output you own, output you can read, output that’s been proven by execution, and a model that outlives any single target language. For the ubiquitous language — the one part of the system that should be the clearest — that’s a trade worth making.

Want to see the output for yourself? Reading the generated C# walks one value object from .koi to .cs, line by line.

Introducing Koine: a language for your domain

Wed, 03 Jun 2026 00:00:00 GMT

Every Domain-Driven Design project starts with the same promise: the ubiquitous language is the single source of truth. A Money value object cannot be negative; an Order in Draft has no lines; an email must look like an email. Everyone agrees. Then the language gets written down three times — in a wiki, in a class diagram, and (eventually, partially, drifting) in C# — and the three copies start disagreeing the moment the first deadline lands.

Koine removes two of those copies. You write the bounded context’s ubiquitous language once, in a small readable DSL, and the compiler emits the idiomatic C# for you: value objects, entities, aggregates, invariants, commands, events, state machines, repositories, the application/CQRS layer, and context maps.

The five-minute version

Here is a slice of a Billing context — a value object with an invariant, a regex-validated email, a smart enum, and an entity with identity:

context Billing {

  value Money {
    amount:   Decimal
    currency: Currency
    invariant amount >= 0        "a monetary amount cannot be negative"
  }

  enum Currency { EUR, USD, GBP }

  value Email {
    raw: String
    invariant raw matches /^[^@]+@[^@]+$/   "invalid email address"
  }

  entity Customer identified by CustomerId {
    name:  String
    email: Email
  }
}

Run koine build billing.koi --target csharp --out ./generated and you get a predictable, nested tree: one folder per context, sub-folders by category (ValueObjects/, Enums/, Entities/, …), plus a tiny Koine/Runtime/ folder with the shared marker types. For example, Money lands at Billing/ValueObjects/Money.cs and Currency at Billing/Enums/Currency.cs — namespaces stay flat (namespace Billing;), only the folders are categorised. The emitted Money.cs is a sealed class : ValueObject whose constructor throws before an invalid instance can exist — no NuGet dependency, no reflection, nothing to learn. It’s the C# you’d have written by hand on a good day, every time.

Why a language, not a library

Plenty of tools give you a DDD base library — a ValueObject<T>, a Result, an aggregate base class. They help, but they leave the actual modeling work (and all the boilerplate) to you, and they put a runtime dependency between your domain and the framework.

Koine takes the opposite bet. The .koi file is the model; the C# is output, not a contract you implement against. That has three consequences worth the trade:

The model reads like the domain. invariant amount >= 0 "a monetary amount cannot be negative" is a sentence a domain expert can check. The generated guard clause is a detail.
The output is yours. It’s plain, dependency-free C# you can read, review in a pull request, and commit to git. Delete Koine tomorrow and the generated code still compiles.
A green build proves the domain. Every emitted type is snapshot-tested and compiled-and-run through an in-memory Roslyn meta-test. When the test suite is green, the generated C# is correct.

How the pipeline works

Koine is strictly layered, and the parser and semantic model are kept target-agnostic on purpose:

.koi source
  → ANTLR lexer/parser
  → semantic model        (no C# concepts live here)
  → semantic validator    (diagnostics with line/column)
  → emitter               (C#, TypeScript, Python, PHP)
  → idiomatic source files

Because no C# concept leaks into the semantic model, adding a second target is “write another emitter,” not “rewrite the compiler.” C# ships today, alongside TypeScript, Python, and PHP emitters, with Rust on the roadmap.

Try it without installing anything

The whole compiler runs in your browser as a WebAssembly module. Open the Koine Studio, edit the model, and watch it recompile to C# the moment you stop typing — no install, no server.

When you’re ready to go deeper, What is Koine? walks through the pipeline, and your first model gets you to generated code in a few minutes. Welcome to Κοινή — the common tongue of your domain.