[Beam] Fable Beam (alpha)

[dbrattli]

Summary

Add a new Erlang/BEAM compilation target to Fable, enabling F# code to be compiled to Erlang source (.erl files) and run on the BEAM virtual machine. This leverages the BEAM's lightweight process model and massive concurrency capabilities from F#, with constructs like MailboxProcessor naturally mapping to the actor-based runtime they were inspired by.

2022 Erlang tests passing, 0 failures. Run with ./build.sh test beam.

Progress Checklist

Compiler Infrastructure

• Language.Beam added to Plugins.fs
• Beam AST definitions (Beam.AST.fs)
• F# → Erlang transform (Fable2Beam.fs)
• Erlang source code printer (ErlangPrinter.fs) — incl. function clause guard printing
• Beam-specific BCL replacements (Beam/Replacements.fs)
• CLI integration (--lang beam / --lang erlang)
• Build system (./build.sh test beam, quicktest, fable-library)
• Replacements.Api.fs dispatch for all API functions
• Erlang keyword escaping in sanitizeErlangName (maybe, receive, etc. → append _)
• Auto-imported BIF clash detection (apply/2, now/0, etc. → auto no_auto_import)
• BIF qualification in ErlangPrinter — Call(None, ...) nodes auto-prefixed with erlang: for known BIFs
• Stray ok atom removal — strips unit values from non-final positions in all body contexts
• defaultof handles all types: Nullable, struct tuples, Builtin (TimeSpan, DateTime, DateTimeOffset, Guid)

Core Language (Phase 2) — Complete

• Arithmetic, comparison, bitwise, logical operators
• If/else, lambda, delegates, curried apply
• Pattern matching (DUs, options, lists, tuples, guards)
• DecisionTree / DecisionTreeSuccess
• Let/LetRec bindings, mutual recursion (named funs)
• Tail call optimization (native in Erlang)
• Mutable variables via process dictionary (with ref erasure at scope exit)
• For/while loops as tail-recursive funs
• CurriedApply via simple List.fold (matches JS/Python targets)
• Custom operator dispatch via SRTP (CustomOp active pattern)

Types (Phase 3) — Complete

• Discriminated unions → tagged tuples {Tag, Field1, ...}
• Records → Erlang maps #{field => value}
• Anonymous records → Erlang maps
• Structural equality via native =:= (deep comparison)
• Classes with constructors, properties, methods
• Object expressions → map-of-closures #{method => fun(...) -> ... end}
• Interface dispatch via maps:get
• Class inheritance (BaseValue support)

Collections (Phase 4) — Complete

• list<T> → Erlang linked lists (natural fit)
• array<T> → process dict refs wrapping Erlang lists (mutable via put/get)
• byte[] → atomics module for O(1) mutable read/write ({byte_array, Size, AtomicsRef})
• Map<K,V> → Erlang native #{} maps
• Set<T> → Erlang ordsets (sorted lists)
• Seq<T> → lazy evaluation via compiled seq.erl/seq2.erl (from Seq.fs/Seq2.fs)
• Dictionary<K,V> → process dictionary + Erlang maps
• HashSet<T> → process dictionary + Erlang maps
• Queue<T> → process dictionary + Erlang lists
• Stack<T> → process dictionary + Erlang lists
• ResizeArray<T> → process dictionary + Erlang lists
• Range expressions, array indexing, array comprehensions

Standard Library — Complete

• Seq module (156 tests) — lazy seqs via compiled seq.erl with auto-uncurried callbacks
• String module (153 tests)
• Array module (146 tests) — incl. fill, blit, sortInPlace, byte array atomics, Array.Parallel
• Arithmetic / Int64 / BigInt (139 tests)
• List module (137 tests)
• Conversions (100 tests) — incl. base conversion, Boolean.Parse, Decimal.Parse/ToString, radix prefixes
• Applicative (84 tests)
• TimeSpan (83 tests)
• Comparison / hash / equality (66 tests) — incl. Unchecked, LanguagePrimitives, Set comparison
• Misc (59 tests)
• DateTime (53 tests)
• Types (50 tests) — classes, interfaces, object expressions, type testing
• Option module (50 tests)
• Map module (50 tests)
• Set module (46 tests)
• ResizeArray (41 tests)
• Char module (38 tests)
• Functions (38 tests)
• Regex (37 tests) — via Erlang re module (PCRE), named groups
• Encoding (35 tests) — UTF8, Stopwatch, Nullable, DateTimeOffset
• Pattern matching (28 tests)
• Records (22 tests)
• Result (21 tests)
• Uri (21 tests)
• HashSet (20 tests) — incl. subset/superset, CopyTo
• Enum (20 tests)
• Union types (18 tests)
• Interop (17 tests) — emitErl, Import, module calls
• Dictionary (17 tests)
• Async (17 tests) — incl. cancellation
• Queue (17 tests)
• Tail calls (15 tests)
• Tuples (15 tests)
• Reflection (11 tests)
• And more: loops, GUIDs, exceptions, stacks, seq expressions, custom operators, anonymous records, try/catch, tasks, DateTimeOffset, nullness, MailboxProcessor, Sudoku integration test

Error Handling (Phase 6) — Complete

• try/catch with erlang:error
• failwith → erlang:error(<<"message">>)
• Exception .Message access
• Result<T,E> → {ok,V}/{error,E}
• Custom F# exceptions (exception MyError of string) → maps with exn_type tag
• Exception type discrimination in catch clauses
• Multi-field exceptions with named fields

Types & Type Testing (Phase 6b) — Complete

• Enums → Erlang integers (native, no special handling)
• Type testing (:?) → is_integer/is_binary/is_float/is_boolean/is_list/is_tuple/is_map
• Exception type testing via exn_type atom tag
• box/unbox erased (TypeCast)
• String interpolation generic formatting (fable_string:to_string/1)
• Curry expressions — compile-time nested lambda wrapping via curryExprAtRuntime
• sprintf, printfn, String.Format support
• System.Tuple/ValueTuple Item1-Item7 access
• RegexConstant support (re:compile)
• ValueOption support

Async, Task & Processes (Phase 7) — Complete

• async { } computation expressions via CPS (continuation-passing style)
• Async.RunSynchronously — runs in same process (preserves process dict)
• Async.StartImmediate — fire-and-forget in current process
• Async.Parallel — spawns Erlang processes, collects via message passing
• Async.Sleep — timer:sleep/1 (cancellation-aware via receive)
• Async.Ignore, let!, do!, return!, try/with in async
• Task CE support (alias for Async)
• MailboxProcessor — Start, Post, PostAndAsyncReply via in-process CPS
• CancellationToken — process dict pattern, cancel/register/cancel_after
• Array.Parallel + Parallel.For — spawns Erlang processes per element
• Runtime: fable_async_builder.erl + fable_async.erl + fable_mailbox.erl + fable_cancellation.erl + fable_parallel.erl

BCL / Interop Support — Complete

• System.Text.Encoding.UTF8 — GetBytes/GetString (identity, Erlang strings are UTF-8 binaries)
• System.Diagnostics.Stopwatch — StartNew/Elapsed/ElapsedMilliseconds/Stop/Reset via erlang:monotonic_time
• Nullable<T> — erased (value identity)
• Unchecked.hash/equals/compare — native Erlang operators
• Convert.ToInt32/ToString with base parameter — via fable_convert.erl
• Boolean.Parse, radix-aware int parsing (0x/0o/0b prefixes)
• DateTime — 2-tuple {Ticks, Kind}, fable_date.erl (53 tests)
• DateTimeOffset — 3-tuple {Ticks, Kind, OffsetTicks}, fable_date_offset.erl (7 tests)
• TimeSpan — plain integer (ticks), fable_timespan.erl (83 tests)
• Guid — UUID v4 via crypto:strong_rand_bytes, fable_guid.erl (10 tests)
• Uri — parsing and manipulation, fable_uri.erl (21 tests)
• BitConverter — byte conversion, fable_bit_converter.erl
• use/IDisposable support
• StringBuilder — Fable-compiled from System.Text.fs → system_text.erl
• Decimal — fixed-scale integer (value × 10^28), fable_decimal.erl

Runtime Library (src/fable-library-beam/)

31 hand-written Erlang modules (all with -spec type annotations for Dialyzer):
fable_list.erl, fable_map.erl, fable_string.erl, fable_option.erl, fable_result.erl, fable_set.erl, fable_char.erl, fable_comparison.erl, fable_convert.erl, fable_reflection.erl, fable_regex.erl, fable_resize_array.erl, fable_dictionary.erl, fable_hashset.erl, fable_queue.erl, fable_stack.erl, fable_async_builder.erl, fable_async.erl, fable_mailbox.erl, fable_timespan.erl, fable_date.erl, fable_date_offset.erl, fable_guid.erl, fable_uri.erl, fable_utils.erl, fable_bit_converter.erl, fable_decimal.erl, fable_cancellation.erl, fable_stopwatch.erl, fable_parallel.erl, fable_seq.erl (hand-written helpers)

Plus Fable-compiled modules from src/fable-library-beam/: Seq.fs → seq.erl, Seq2.fs → seq2.erl, Range.fs → range.erl, System.Text.fs → system_text.erl

Not Yet Implemented

• OTP patterns (supervision, hot code reload)
• Nested modules
• Integer wrapping semantics (Erlang has arbitrary-precision integers)

Design Decisions

F# Concept	Erlang Representation
Records	Maps #{field => value}
DU cases	Tagged tuples {tag, Field1, Field2}
Options	None = undefined, Some(x) = x (erased)
Result	{ok, V} / {error, E}
Classes	make_ref() + process dictionary
Interfaces	Map-of-closures #{method => fun}
Exceptions	Maps with exn_type atom tag
Sets	ordsets (sorted lists)
Arrays	Process dict refs wrapping Erlang lists
Byte arrays	atomics module ({byte_array, Size, Ref}) for O(1) read/write
Sequences	Lazy seqs via compiled seq.erl/seq2.erl
Enums	Plain integers
Integers	Native arbitrary-precision
Decimal	Fixed-scale integer (value × 10^28)
Mutability	Process dictionary (with ref erasure at scope exit)
DateTime	2-tuple {Ticks, Kind} (100ns intervals from Jan 1, 0001)
TimeSpan	Plain integer (ticks)
Async	CPS funs fun(Ctx) -> ok end with #{on_success, on_error, on_cancel}
Task CE	Alias for Async (same CPS infrastructure)
MailboxProcessor	In-process CPS continuation model
CancellationToken	Process dict pattern with timer-based auto-cancel
Curry	Compile-time nested lambda wrapping (no runtime module)
Dictionary/HashSet	make_ref() + process dictionary + Erlang maps
Queue/Stack	make_ref() + process dictionary + Erlang lists
ResizeArray	make_ref() + process dictionary + Erlang lists
Regex	Erlang re module (PCRE-based)
Encoding.UTF8	Identity (Erlang strings are UTF-8 binaries)
Stopwatch	erlang:monotonic_time(microsecond)

Test plan

• 2010 Erlang tests passing via ./build.sh test beam (57 test files)
• .NET tests pass in parallel (same test files run on both)
• Integration test: Sudoku solver using Seq, Array, ranges
• Integration test: 2048×2048 raytracer (~40s on BEAM, atomics byte arrays)
• CI: GitHub Actions build-beam job

🤖 Generated with Claude Code

[github-advanced-security]

Ionide.Analyzers.Cli found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[MangelMaxime]

@dbrattli Great work :)

Before merging, I think it would be nice if we could also update .devcontainer/Dockerfile.

This is used for:

• making Release build from MacOS (.NET has a bug in OSX when compiling fable-compiler-js in release mode)
• debugging TimeZone issues
• easy to setup environment for quick contribution / from the browser