Mezze is a functional language on GraalVM. Records and variants hold data, abilities give shared behaviour to your own types, and effects account for everything a function reaches outside itself. Types are inferred, so you annotate where it helps a reader rather than to satisfy the compiler.

The parts are meant to be few, and to be reused. A function’s parameter list is a record. An ability is a named set of operations, and so is an effect. They are written the same way and read the same way; what differs is who supplies the operations and when. An ability is implemented by a type, and the compiler resolves the call at the site. An effect is supplied by a handler somewhere up the call stack, and the typechecker tracks which effects a function still needs before it can run.

Learn records well and most of the syntax is already familiar.

Why the name

Mezze is a spread of small dishes, where the meal is the combination rather than any one plate. That is the intent here too. A few simple constructs, combined, cover what larger languages need dedicated features for.

The other half of the name is the table. Mezze is shared food, and the language is built for programs that are shared as well, running across threads and eventually across machines, with the effect system tracking what touches what.

What to read next

Start with primitives and functions, then records. Effects come later, but they are the part that makes the rest unusual, so do not stop before them.

Mezze reuses a small number of symbols, and each one means the same thing everywhere it appears. This page is the key. Every later section assumes it.

Comments

# starts an ordinary comment and runs to the end of the line.

## is a doc comment. It attaches to the declaration below it and is what hover and the LSP show, so it is worth writing in full sentences.

#{ ... } is a metadata comment, a record of facts about the declaration. Some fields are acted on by the compiler, such as deprecated = True, and others are there for tooling or for a reader.

# an ordinary note to a reader

 ## Returns the larger of two values.
 ## Works for any type that implements Ord.
 #{ deprecated = True, message = "use std::math::max instead" }
 let bigger = { a, b } -> if a.gt { r = b } then a else b

Curly braces are records

{ ... } is a record, and that holds in every position. A record literal, a function’s parameter list, a record type, a pattern that destructures one, and the argument list at a call site are all the same construct:

let point = { x = 3, y = 4 }              # a value
let area = { w, h } -> w * h              # parameters
let { x, y } = point                      # destructuring
area { w = 3, h = 4 }                     # arguments

{} with nothing in it is the empty record, which is also the unit value. A function taking no arguments is written {} -> and called with {}, and a method with no arguments is .size {}.

Abilities and effects use the same braces, because they are named sets of operations and an operation is a function. ability Ord for 'a where { ... } and effect Log where { ... } both hold their operations in a record, and an impl supplies the matching one.

Parentheses group

( ... ) does one job: it groups an expression so precedence works out. (1 + 2) * 3, or (0.1 + 0.2).to_str {} to call a method on the sum rather than on 0.2.

Inside a string, $( ... ) is the same brackets doing the same job. The dollar marks an interpolation and the parens group the expression, so anything that evaluates to a Str fits, including a whole method chain.

Square brackets are sequences

[1, 2, 3] is a sequence literal, and [Int] is its type. The same brackets, one holding values and one holding a type.

Vertical bars are variants

type Status = | Queued, Shipped { days: Int } | declares a variant, with the cases between bars. A trailing ... before the closing bar leaves it open.

In a match, a bar is not needed: arms are written one per line. The | in a type declaration and the arms of a match are separate syntax for the same idea.

Annotations

A type annotation can sit in three places, and you can use any combination:

let shout : { msg: Str } -> {} <Log> = { msg } -> ...   # the whole binding
let area = { w: Int, h: Int } -> w * h                  # individual parameters
let n : Int = area { w = 3, h = 4 }                     # a local binding

Annotating the whole binding is the only form that can state an effect row or a with constraint, so it is what a public function usually carries. Everything else is inference, and none of it is required.

with adds a constraint on a type variable. It sits before the arrow:

let bigger : { a: 'a, b: 'a } with Ord 'a -> 'a = { a, b } -> ...

That signature accepts any type at all, provided it implements Ord. Without the constraint the body could not call .gt {}, because nothing would guarantee the type has it.

Angle brackets are the effect row

<Log> after a return type says the function performs the Log effect and cannot run until a handler supplies it. A function that performs nothing has no row at all.

The row is a list, and two symbols can appear in it.

... stands for “whatever else the caller brings”. <Http, ...> means this function needs Http, and passes through any other effects its arguments perform. A bare <...> is the same idea with nothing named: list::map is written { xs: List 'a, f: { x: 'a } -> 'b <...> } -> List 'b <...>, which says whatever the callback performs, map performs too. That is why you can call println inside a .map {} without map knowing about Log.

* marks effects that have been handled. A bare <*> means all of them were, which is what you see on main. <Http, *> means some were handled and Http was not, so the caller still has to supply it:

let report = { url } -> perform Console in
  println { msg = request { url }.send {}.text_or { def = "offline" } }

# report : { url: Str } -> {} <Http, *>

perform Console in discharged Log, leaving Http named in the row.

Match and guards

match x is opens a match, and each arm is pattern -> expression. A pattern can be a variant case, a record, a literal, or a binding. Add if after the pattern for a guard:

match s is
  Shipped { days } if days == 0 -> "arriving today"
  Shipped { days } -> "arriving in $(days.to_str {})"
  Queued -> "waiting"

Arms are tried top to bottom, so the literal case above has to precede the one that binds days. A match must cover every case, and the compiler will not accept one that does not.

Names

An ordinary name starts with a lowercase letter or an underscore, and may contain letters, digits and underscores after that. snake_case is the convention for values and functions, and a leading underscore marks something deliberately unused.

Types, variant cases and abilities are UpperCamelCase: Status, Shipped, NumAdd. That casing is a convention rather than a rule, and the compiler will accept a capitalised binding, but every name in the stdlib follows it and patterns read better when a constructor is visibly distinct from a binding.

A type variable starts with an apostrophe: 'a, 'k, 'v. Those are the placeholders in a generic signature, and by convention 'a is the first, 'k and 'v are a map’s key and value.

Operators

The full set is deliberately small.

+ - * / % for arithmetic, == != for equality, < <= > >= for ordering, and && || for logic. That is the whole set.

None of them is built in. Each desugars to an ability, so + calls NumAdd and < calls Ord, and implementing that ability is what makes the operator work on your own type.

There are no prefix operators at all. Boolean negation is .not {} and arithmetic negation is .neg {}.

Reaching for !x gets you a parse error saying so. The reason is uniformity: a method reads the same as every other operation on a value, participates in a chain, and needs no precedence rule of its own. - in front of a number literal is still ordinary syntax; it is only the prefix operator that is absent.

Modules

:: separates the parts of a module path, and use brings names into scope:

use std::effects::log::{ Console, println }   # selected names
use std::collections::map                     # the module itself

The first form puts Console and println in scope directly. The second puts map in scope, so its contents are reached as map::empty {}. Reach for the second when a bare name would be ambiguous: map::empty and set::empty read better than two imported emptys.

pub marks a declaration as visible outside its module, and pub use re-exports a name that came from elsewhere.

impl, and where for goes

impl covers three different jobs, told apart by whether for appears and what follows it:

impl Ord for Int where { ... }          # Int implements the Ord ability
impl Log for Console where { ... }      # Console is a handler for the Log effect
impl Bool where { ... }                 # methods on Bool itself, no ability

The first two read the same because they are the same shape: a named set of operations, and something supplying them. What differs is that Int is a type implementing an ability, while Console is a handler supplying an effect.

The declarations differ slightly. An ability names the type it is about, because it is written once and implemented many times:

ability Ord for 'a where { ... }
effect Log where { ... }

An effect does not, because the thing supplying it is a handler rather than the type the operations act on.

Keywords

let	bind a value
type	declare a type or alias
newtype	declare a distinct wrapper
effect	declare an effect
ability	declare an ability
impl	implement an ability, supply an effect handler, or add methods to a type
use	import
pub	export
as	rename an import
if then else	conditional
match is	pattern match
do	sequence statements
perform in	supply a handler
with	constrain a type variable
having	fix an associated type
where	open a body of operations
for	name the type an ability, impl or handler applies to
abort resume	abort and resume continuations, inside a handler
scope	effect handler scopes

All of it together

Waiting for the Mezze runtime…

Nothing on this page is annotated and all of it has an exact type. Hover any name in the editor at the bottom to see what the compiler worked out.

Int

A signed 64-bit integer, written 42. Arithmetic saturates at the bounds rather than wrapping: adding one to the largest Int gives the largest Int back, not a negative number. That is the safer failure of the two, since a value stuck at the maximum is easier to notice than one that silently changed sign.

Nat

A non-negative 64-bit integer, written 5n. A count that cannot go below zero says so in its type instead of relying on a comment or a runtime check.

Going from Int to Nat can fail, so int::to_nat hands back an Option rather than guessing.

Subtracting two Nats gives an Int, because the answer can be negative. The type follows what the operation can actually produce rather than what its inputs happened to be.

Float

A 64-bit IEEE 754 double, written 1.5. Same representation as double in C or Java, with the same infinities and NaN.

Frac

An exact rational, written 1//3. It holds a numerator and a denominator rather than a binary approximation, so thirds stay thirds and no value is unrepresentable. Arithmetic keeps the fraction reduced.

Bool

Bool is a variant with two cases, True and False. Nothing about it is special to the compiler: the capitals are there because those are constructor names, the same as Some or Ok, and you can match on them the way you match any other variant.

&& and || are the operators, and they are not built in either: they desugar to the LogicalAnd and LogicalOr abilities, which Bool implements like any other type would. Boolean negation is .not {}, since Mezze has no prefix operators.

Str

A string of Unicode text. Interpolation puts an expression inside a string, so "$(name) has $(count.to_str {}) letters" splices both values in. The interpolated expression has to be a Str, which is why count calls to_str {} rather than sitting there bare. That is stricter than most languages and deliberate. A value that quietly converts itself is how a log line ends up reading [object Object], or how a missing value becomes the four characters null in a report.

A string can also run across several lines. There is no separate syntax for it, no triple quotes and no continuation character. Open a quote, write the lines, close it. Newlines and leading spaces are kept exactly as typed, and interpolation works the same as on one line.

Char

A single character. There is no character literal syntax, so a Char comes from char::from_str, which returns an Option because the string might not hold exactly one.

Seq

The literal container, written [1, 2, 3]. Indexed and contiguous, and the one most code reaches for. It holds a single type, so [Int] cannot be given a Str.

List

A linked list. Cheap to push onto the front and to take apart at the head, which suits recursion and building a collection one element at a time.

Map and Set

Hashed, so lookup is fast and iteration order is not promised. A Set drops duplicates on insert; a Map replaces the value at a key.

SortedMap and SortedSet

The same operations with keys kept in order. Iteration is sorted and range queries are possible, which costs a little on insert.

Deque

A double-ended queue. Pushes and pops at both ends are cheap, so it works as a stack or a queue without changing type.

Bytes

A sequence of raw bytes rather than characters. This is what file and network operations carry, and bytes::to_str decodes it when the bytes really are text.

All of it together

Containers are built by chaining from an empty one, and the methods carry the same names wherever the operation means the same thing.

Waiting for the Mezze runtime…

A record is a set of named fields. Writing one is all it takes; there is no declaration step and no class to define first.

let point = { x = 3, y = 4 }

point has the type { x: Int, y: Int }, which is a description of its shape rather than a name someone chose. Two records with the same fields are the same type, whatever the code that made them.

Structural, not nominal

This is the part that differs from most typed languages. A function asking for { city: Str, temp: Int } accepts any record with those fields, from anywhere, with no declaration in common.

That cuts both ways, and it is worth knowing which way you want. Structural typing means less ceremony and no import just to name a shape. It also means two unrelated concepts that happen to share fields are interchangeable. When you want them kept apart, that is what newtypes are for.

Copy, do not mutate

A record is a value. To get one with a field changed, spread the original and name what differs:

Waiting for the Mezze runtime…

The spread copies every field the original had and the ones you name replace them. Nothing is modified, so the value you spread from is still whatever it was.

Destructuring uses the same braces to take a record apart. And because a function’s parameter list is a record, { x, y } -> in a signature is the same construct doing the same job.

Naming a shape

type gives a shape a name. The name is an alias, not a wrapper: a Reading is { city: Str, temp: Int }, and anything with those fields is one.

type Reading = { city: Str, temp: Int }

let describe : { r: Reading } -> Str = { r } ->
  "$(r.city) at $(r.temp.to_str {})"

describe { r = { city = "Lisbon", temp = 21 } }   # no conversion needed

So an alias buys readability rather than safety. The signature says Reading instead of repeating the fields, and hover shows the name. If you want a type the compiler will keep separate from its contents, reach for a newtype.

Closed and open

A record type is closed by default: exactly these fields and no others. A trailing ... opens it, meaning at least these fields.

Waiting for the Mezze runtime…

Open records are how you write a function that cares about part of a value. label needs a city and is honest that it ignores the rest, so it works on a Reading, on a richer record, and on anything a caller invents later.

Prefer closed when the shape is the point, and open when you are reaching for one field. An open type in a return position is rarely what you want, since it promises the caller less than you know.

A variant is a value that is one of several named cases. Cases sit between pipes, and a case may carry fields of its own.

type Status = | Queued, Shipped { days: Int }, Cancelled { why: Str } |

Queued carries nothing. Shipped carries a days, Cancelled a why. A Status is exactly one of the three, and the compiler knows which cases exist.

With a name, or without

The type above is an alias, the same as for a record: it names the shape so you can say Status instead of repeating the cases. The variant can also be written inline where it is used:

Waiting for the Mezze runtime…

Inline suits a two-case switch used in one place. A name is worth it as soon as the type appears in more than one signature, or as soon as the name says something the cases do not.

Matching

match x is takes a variant apart. Each arm names a case, binds any fields it carries, and gives the result for that case.

Waiting for the Mezze runtime…

Three arms match Shipped and they are tried in order, so the specific ones come first. Shipped { days = 0 } matches a literal. Shipped { days } if days > 7 adds a guard, an ordinary boolean expression that has to hold for the arm to be taken. The last one binds days and catches the rest.

Miss a case and it will not compile

A match has to cover every case the type admits. This one leaves out Cancelled — press Check and the compiler names exactly what is missing:

Waiting for the Mezze runtime…

error[V0601]: This match expression doesn't handle all cases. Missing case:
Cancelled. Add the missing patterns or use `_ ->` as a catch-all.
  = hint: add a case for: Cancelled

Add the arm and it compiles. This is the reason variants are worth declaring: add a fourth case to Status a year from now and every match that needs updating becomes a compile error, listed by name, instead of a branch that silently does nothing.

Two more the compiler catches

An arm after a catch-all can never run, and saying so is more useful than letting it sit there looking meaningful:

Waiting for the Mezze runtime…

error[V0603]: Unreachable pattern: Previous pattern already matches all cases
  = hint: this pattern can never match because an earlier pattern already covers it

And a case the type does not have is caught where you wrote it, with the ones that do exist listed:

Waiting for the Mezze runtime…

error[V0704]: Variant type does not have constructor 'Refunded'.
Available constructors: 'Queued', 'Shipped'

Between them and V0601, a match is checked from both sides: no case left out, and no arm that cannot match.

Open variants

A trailing ... leaves a variant open, meaning “these cases, and possibly others”:

Waiting for the Mezze runtime…

An open variant is the mirror of an open record. A closed one is a promise about the whole set of cases, which is what makes exhaustiveness checking possible; an open one gives that up in exchange for extension. Because the set is not known, a match on an open variant needs a catch-all arm — and that catch-all is exactly what stops the compiler telling you about a case you forgot.

Reach for closed by default. The compile error when you add a case is the feature, and opening a variant turns it off.

Two ways to put a name on a type, and they do opposite things. An alias is a shorthand the compiler forgets; a newtype is a distinct type it enforces.

type is a shorthand

type gives an existing type another name. Nothing changes but the reading.

type Celsius = Int

let t : Celsius = 21     # an Int, called Celsius

Celsius is Int. No conversion on the way in, none on the way out, and an ordinary Int is accepted anywhere a Celsius is asked for. The name shows up in signatures and on hover, and that is the whole benefit.

That makes an alias right when the shape is long and the meaning is obvious: type Reading = { city: Str, temp: Int } saves repeating four tokens. It is the wrong tool when the point is to stop two values being confused, because it does not stop anything.

newtype makes a real type

newtype wraps a type in a new one the compiler keeps separate.

Waiting for the Mezze runtime…

Money and UserId are both Int underneath and neither is interchangeable with the other, or with a bare Int. Passing one where the other is expected is a compile error:

error[T0201]: Field `m` expects Money but got Int in call to `f`

That error is the reason to reach for a newtype. An identifier, a quantity and an amount of money are all integers, and mixing them up is the kind of bug a type system should be catching.

Wrapping and unwrapping

Money.(350) constructs. The same syntax in a pattern position takes it apart:

let price = Money.(350)          # wrap

match price is
  Money.(n) -> n                 # unwrap, n : Int

There is no field access, and that is deliberate. Getting at the contents means matching, which means the unwrapping is written down where it happens rather than scattered through the code as .val.

Hiding the representation

Attach behaviour to the wrapper and callers never see the inside at all:

Waiting for the Mezze runtime…

price.to_str {} formats as currency because Money says what that means. Nothing outside the impl needs to know money is stored in cents, and if that changes to a Frac later, only this block changes.

Which to use

Alias when the name is for the reader: a long record shape, a type that recurs across signatures. It costs nothing and prevents nothing.

Newtype when the name is for the compiler: money, identifiers, units, anything where two values of the same underlying type must not be swapped. You pay a wrap and an unwrap, and you get an error instead of a bug.

A function is { params } -> body, and the parameter list is a record. Not “like a record” — it is one. So every argument is named at every call site, and Mezze has no positional arguments at all.

Waiting for the Mezze runtime…

Why names, not positions

Argument order stops being something to remember. rect { width = 3, height = 4 } and rect { height = 4, width = 3 } are the same call, so there is no convention to learn per function.

The bigger win is reading. Take a call written positionally:

send_mail("[email protected]", "[email protected]", "New offer inside")

Which address is the sender? You cannot tell. You go and look at the definition, or you trust that whoever wrote it got the order right. Reviewing a diff that swaps those two arguments, you would have to know the signature by heart to catch it.

The same call in Mezze:

send_mail { from = "[email protected]", to = "[email protected]", subject = "New offer inside" }

Now the call site says what each value is for. Nothing about the types changed, and newtypes are still worth reaching for when a value deserves its own type. This is about the reader: the information was always there in the function definition, and named arguments carry it to where the code is actually read.

That matters more than it used to. Code is read far more often than written, and a growing share of it is written by a model. A model generating the second form has the field names to check itself against and can see immediately that from and to are the wrong way round. Generating the first form it has only position, and position is exactly the information that a reader, human or otherwise, cannot recover from the call.

Currying comes free

Currying means calling a function with some of its arguments and getting back a function that wants the rest. It is how you turn a general operation into a specific one: given a function of two things, fix one and you have a function of the other.

In most languages this is awkward. Arguments have an order, so you can only fix them left to right, and library authors spend real effort deciding which argument goes first so that partial application is useful later. Get it wrong and callers reach for a lambda instead.

Here it is just record application. Give a call some of the fields and you get a function expecting the ones you left out:

let rect = { width, height } -> width * height

let strip = rect { height = 1 }
strip { width = 12 }

Any subset works, in any combination, because the fields are named. There is no privileged first argument.

The error messages are the part worth dwelling on. A curried function in a positional language often fails somewhere far from the mistake, with a message about a function type rather than about your call. Here a partially applied function still takes a record, so the compiler can talk about fields:

error[T0203]: Extra field(s) 'depth' in call to 'strip'.
Function expects fields: width

That is strip from above, called with the wrong field name. The compiler knows height was already supplied and that width is what remains.

The pipe operator

A pipeline reads left to right in the order things happen, rather than inside-out the way nested calls do. |> takes the value on its left and feeds it into the call on its right, with @ marking where it lands:

"  alice , bob , carol  "
  |> str::split { s = @, delimiter = "," }         # @ is the string to split
  |> seq::map { xs = @, f = { x } -> x.trim {} }   # @ is the sequence to map
  |> str::join { strings = @, separator = ", " }   # @ is the pieces to join
  |> str::concat { l = "members: ", r = @ }        # @ is the second field now

Read top to bottom, each line is one step: split the line on commas, trim each piece, join them back, tag the result. The nested-call form of the same thing reads inside-out — concat { l = ..., r = join { strings = map { ... }, ... } } — and you assemble it from the middle.

Notice where @ sits. On the first three steps it is the leading field; on the last it is the second. That is the whole point of the placeholder.

Languages that have pipes usually have to pick a convention. Some are “data first”, so the piped value always becomes argument one; others are “data last” and it always becomes the final argument. Both exist because neither suits every function, and libraries end up ordering their parameters around whichever one their language chose.

Mezze does not have to choose. @ goes wherever the value belongs, so |> works with any function without that function having been designed for it.

Working for any type

A function does not have to name concrete types. Where a parameter could be anything, its type is a type variable — an apostrophe and a name, 'a, standing for “some one type, the same everywhere it appears”. Write a function that only moves values around and it is already polymorphic; you do not ask for it, and you do not annotate it:

Waiting for the Mezze runtime…

Hover swap and its type reads { pair: { second: 'b, first: 'a } } -> { first: 'b, second: 'a }. Two different variables, because the two fields need not match; 'a and 'b are inferred, not written. The one call above fixes them to Int and Str, and a different call fixes them to something else. One definition, every pair.

The moment the body actually does something to the value, that need becomes part of the type. Compare two of them, and the type variable picks up a constraint:

Waiting for the Mezze runtime…

Hover larger: { a: 'a, b: 'a } with Ord 'a -> 'a. Both fields are the same 'a this time — you compared them, so they must be the same type — and with Ord 'a appeared on its own. > comes from the Ord ability, so the compiler records that larger works for any type that has Ord, and nothing else. Call it on ordered types and it runs; call it on a type without Ord and the error is about the missing ability, at the call, not deep inside the body.

None of that was annotated. As everywhere else, the annotation is optional and the inference is the same either way — a public function usually writes the signature down so its constraints read at a glance:

let larger : { a: 'a, b: 'a } with Ord 'a -> 'a = { a, b } -> if a > b then a else b

with states the constraint, and it is the only form that can. This is also exactly how the standard library is built: list::map is { xs: List 'a, f: { x: 'a } -> 'b } -> List 'b — any element type in, any element type out — and math::max is { l: 'a, r: 'a } with Ord 'a -> 'a, the same shape as larger. Abilities is where Ord and constraints like it come from.

The arrow carries the effects

A function’s type is not only what goes in and what comes out. It also records what calling it does:

{ url: Str } -> Str <Http>

The part in angle brackets is the effect row, and it belongs to the arrow rather than to either type beside it. Calling this reaches the network; the Str that comes back is an ordinary Str.

An effect a function does not handle raises to that function’s own arrow, and calling it raises the effect again to the caller:

let outer = {} -> do
  let inner = {} -> do
    fetch { url = "https://example.com" }   # performs Http, not handled here
  # inner : {} -> Str <Http>                  raised to inner's arrow
  inner {}                                  # calling inner incurs it
# outer : {} -> Str <Http>                    raised again to outer's arrow

Neither inner nor outer mentions the network, and both types say <Http>. That is the guarantee: between the operation and the handler that catches it, every arrow in the chain declares it.

A function that performs nothing has no row at all, and that absence is worth as much as the row. { x: Int } -> Int is a promise, not an omission.

Effects covers handlers, the * marker and the rest of the model.

An effect is a property of a computation, not of a value. A record, a number, a string: none of them carries an effect. A function arrow does, and it means “calling me does this”.

{ url: Str } -> Str <Http>

Read that as: give me a URL, I give you a Str, and getting it reaches the network. The effect sits on the arrow because it describes the act of calling, not the answer.

Values are bare

Bind an effectful call to a name and the name has the plain type:

let page = fetch { url = "https://example.com" }   # page : Str

page is a Str, not a Str carrying a network request. The <Http> has gone somewhere else, and where it goes is the whole model.

Effects raise to the enclosing arrow

An unhandled effect rises to the nearest enclosing function, and each call raises it again to its caller, until something handles it.

Waiting for the Mezze runtime…

Hover the four names in that editor. inner and outer both read {} -> Str <Http>, though neither mentions the network in its body: inner inherited the effect by calling fetch, and outer by calling inner. That is what “effects at the function boundary” means, and it is why an effect cannot hide. It is on every arrow between the operation and its handler.

perform handles a computation

perform H in body installs the handler H for the computation body. The body has to be something that does something: a call, a do block, or the body of a function.

A bare value does nothing, so handing one to perform is a compile error:

let page = fetch { url = "https://example.com" }
perform MockHttpClient { rules = [] } in page      # V0510

By the time page exists the request has already happened and the effect has risen to the enclosing function. There is nothing left for a handler to catch, and the compiler says so rather than silently doing nothing:

error[V0510]: Handler 'MockHttpClient' handles 'Http',
but the `perform` body performs no effect.

The star is a purity certificate

Handle an effect and the arrow keeps a mark: <*>. It means “effects were performed here, and handled here”.

let fetch   = { url } -> …            # <Http>    performs, unhandled
let handled = {} -> perform … in …    # <*>       performed and handled
let double  = { x } -> x * 2          #           no row at all

The distinction is worth the symbol. An arrow with no row certifies that nothing effectful runs inside, so the call can be memoised, reordered or run in parallel. An arrow with <*> did real work and cleaned up after itself. Most effect systems erase a handled effect and cannot tell you the difference.

Handling one effect at a time

A handler discharges the effect it handles and leaves the rest alone. Read the comments from the inside out: each perform removes one name from the row, and the star appears the moment anything has been handled at all.

Waiting for the Mezze runtime…

The innermost line is what snapshot promised: three effects, none handled. Each handler above it takes one name away and puts the star there instead. MemoryFS settles FileSystem, SystemTime settles Time, and only when the outermost handler settles Http does the row become a bare <*>.

So the star is not “handled” — it is “handled, and nothing remains”. A row like <Http, *> is the useful middle: some effects are settled, Http is still the caller’s problem, and the type says which. Partially handled code is ordinary code, and it stays honest about what is left.

Swapping the handler

Because the handler is chosen by the caller and not by the function, the same code runs against different worlds. MockHttpClient above answers from a canned rule and never touches a socket, which is what makes the example runnable on this page. Swap it for HttpClient and the identical fetch goes to the network.

That is the practical payoff: a test supplies a different handler, not different code.

More than one effect

An arrow lists everything calling it performs. A function that fetches and then writes what it got carries both:

Waiting for the Mezze runtime…

cache : { url: Str, path: Str } -> Str <FileSystem, Http>. Neither effect is handled inside it, so both raise to its arrow and both have to be supplied by a caller.

Handlers can be listed together, perform Console, MemoryFS in …, or nested when one takes arguments as MockHttpClient does. Both forms discharge what they name and leave the rest to rise further.

Note what the mocks buy here. MemoryFS holds the file in memory, so the example writes and reads a real file without touching your disk, and MockHttpClient answers without a socket. The same cache runs against LocalDisk and HttpClient unchanged.

Your own effects

Nothing above is built in. An effect declares operations and leaves them unimplemented; a handler supplies them.

Waiting for the Mezze runtime…

checkout : {} -> {} <Audit>, and that is the whole point. Its type says it records an audit trail. It does not say a file is involved, because that is the handler’s business: ToFile chose a file, and a different handler could collect the lines in memory, send them to a service, or drop them.

The declaration and the handler read like an ability and its impl, and that is deliberate. What differs is who supplies the operations and when: a type implements an ability and the compiler resolves the call, while a handler supplies an effect and perform decides which one is in scope.

The row can be a variable

Every row so far named its effects. A row can instead say “whatever the caller’s function performs”, written <...>. This is how a higher-order function stays usable with both pure and effectful callbacks.

Waiting for the Mezze runtime…

doubled has no row at all: a pure callback went in, so nothing effectful happens and the certificate from the previous section still holds. fetched carries <Http, ...>, the effect the callback performed. One definition of apply, and it neither forces a caller to be effectful nor blocks one that is.

Both forms appear:

• <...> alone means “exactly what the callback performs, nothing added”.
• <Http, ...> means “Http, plus whatever the callback performs”. The function reaches the network itself and passes the rest through.

This is why seq::map works the same whether you map a pure function or one that prints. Without it the standard library would need a pure copy and an effectful copy of every combinator.

Two rules about where effects may run

The top level is for definitions. A module-level binding whose value performs an effect is rejected, because that would run at module-load time. Defining an effectful function is fine, since an arrow is latent until called.

error[V0502]: Top-level `x` performs an effect at module-load time.
The top level is for definitions — effectful code must run inside a function.

The entry point must handle what it uses. The runtime supplies the ambient effects. An effect you declared yourself, left unhandled on the entry’s arrow, is a compile error rather than a surprise at run time:

Entry 'main' performs Audit, but nothing discharges it — the entry has no
enclosing handler, so it leaks at runtime.

An ability is a set of methods a type can implement. Declare the ability once, implement it for as many types as you like, and code written against the ability works for all of them.

ability Shape for 'a where { area: { it: 'a } -> Int }

'a is the implementing type, and it is the receiver — the value the method is called on. Both are ordinary names in an ordinary record: an ability declaration is a record of function types, in the same braces as everything else in the language.

Implementing it

An impl supplies the methods for one type.

Waiting for the Mezze runtime…

A square and a rectangle store different fields and compute area differently. What they share is that both answer area, and that is enough for anything written against Shape.

Writing against the ability

A function that calls area works for any type that implements it. There is nothing to declare: the constraint is inferred from the call.

Waiting for the Mezze runtime…

Add a fourth shape a year from now, give it an impl, and describe works on it without being touched.

Call the method on a type with no implementation and the compiler says so, and lists what does implement it:

error[Constraint Solving]: Int does not implement 'Shape'.
To enable this, implement: impl Shape for Int where { ... }
  Available impls: impl Shape for Square

With a name, or without

Records and variants can be written inline rather than named, and the target of an impl is no different. This implements Shape for a bare record shape, with no alias anywhere:

Waiting for the Mezze runtime…

An alias is only a name

A type does not create a new type, it names an existing shape. So an impl written against the name is found by a value that never mentions it:

Waiting for the Mezze runtime…

Name the target when the name is the clearer thing to read. The values it covers are the same either way.

More than one method

An ability can require several methods. Each impl supplies all of them, separated by commas, the same as any other record.

Waiting for the Mezze runtime…

Abilities and effects

The two look alike on purpose. Both declare a set of operations in a record of function types, and both leave the implementation to be supplied elsewhere. The difference is who supplies it and when.

An ability is chosen by the type of the receiver, decided at the call site and fixed once the type is known. An effect is chosen by the handler that is in scope, decided by whoever runs the computation, and the same code can run under a different handler tomorrow. Reach for an ability when behaviour belongs to a type; reach for an effect when it belongs to the context the program runs in.

A module is a file. Its path under src is its name, so src/shop/money.mz is the module shop::money, and :: separates the parts of that path everywhere it appears.

Two ways to import

use brings something into scope, in one of two shapes:

use std::effects::log::{ Console, println }   # selected names, used bare
use std::collections::map                     # the module, used qualified

The first puts Console and println directly in scope. The second puts map in scope, and its contents are reached through it as map::empty {}.

Prefer the qualified form when a bare name would be ambiguous or uninformative. map::empty and set::empty sit happily in one file; two imported emptys do not. Prefer the selective form for names that read well alone, which is why every example on this site imports println rather than writing log::println.

A module can also be renamed on the way in:

use std::collections::map as m

m::empty {}

pub decides what escapes

A declaration is private to its module unless marked pub.

## A price in cents.
pub newtype Money = Int

pub let of_cents : { n: Int } -> Money = { n } -> Money.(n)

pub let cents : { m: Money } -> Int = { m } -> match m is
  Money.(n) -> n

# No pub: an implementation detail, invisible outside this file.
let double = { m: Money } -> Money.(cents { m = m } * 2)

Reaching for double from another module is a compile error that says what to do about it:

error[V0702]: 'double' exists in module 'money' but is not public.
Add 'pub' to export it.

That is the useful pairing with newtypes. Export the type and the operations that make sense on it, keep the representation private, and callers cannot depend on money being an Int because they can never see that it is.

pub use re-exports something imported from elsewhere, so a module can present a curated surface without callers knowing where each piece came from.

A project

A single file is enough to try something, and mez check file.mz will type it. A project adds Mezze.toml:

[package]
name = "shop"
version = "0.1.0"

[[app]]
name = "shop"
path = "src/app.mz"
entry = "main"

entry names the function the program starts at. That function is where effects have to be handled: the runtime supplies the ambient ones, and a user-defined effect left unhandled on the entry’s arrow is a compile error rather than a failure at run time.

Entry 'main' performs Audit, but nothing discharges it — the entry has no
enclosing handler, so it leaks at runtime. Wrap the body in a handler:
`perform <Performer> in …`

That error is the last link in the chain Effects describes. An effect raises from where it is performed, through every arrow that calls it, up to the entry — and if nothing has handled it by then, the program does not compile.