The Saga Guide

Learn Saga from the ground up, from Hello World to effects, handlers, and concurrency.

Using Saga with an AI assistant? Drop /llms.txt into context for an index of guides, or /llms-full.txt for the whole guide concatenated.

Language Tour

A quick overview of everything Saga offers, in one page.

Install Erlang, the Saga compiler, and set up your editor.

Your first Saga program, basic commands, and a quick taste of the language.

Bindings, primitive types, operators, blocks, strings, and pipes.

Definitions, annotations, pub/private, lambdas, currying, and composition.

ADTs, records, tuples, type parameters, opaque types, and dictionaries.

Case expressions, guards, destructuring, list/record/string patterns, and exhaustiveness.

do...else for sequential pattern binding, and list comprehensions.

Type-driven dispatch with Show, Eq, Ord. where clauses, supertraits, and deriving.

Declaring effects, performing with !, writing handlers, resume, and abort.

The Fail effect, to_result, Result vs Fail philosophy, panic, and catch_panic.

Named, inline, let-bound, and factory handlers. Stacking, ordering, and the return clause.

Row polymorphism, effect signatures on higher-order functions, subtyping, and multishot continuations.

Effect-based testing with describe, test, handler swapping, and CI integration.

Project layout, project.toml configuration, module declarations, imports, pub visibility, and qualified access.

Hex, git, and path dependencies. saga install, the lockfile, transitive deps, NIF compilation with rebar3, and the dep cache.

The Actor effect: spawn, send, receive. Isolation and message passing on the BEAM.

Supervision as a handler pattern. Restart strategies, backoff, and let-it-crash.

Binary construction, pattern matching, segment specifiers, and Std.BitString.

Atomic references for controlled mutable state. When to use refs vs recursion.

Calling Erlang, Hex dependencies, git deps, and project.toml configuration.

Make your own traits derivable. The Generic representation, building-block instances, and the rules a derivable trait must follow.