Wax language
specification

Overview#

Wax is a statically typed, embeddable language built for perfect reproducibility. Given the same initial state and inputs, a Wax program will always follow the exact same execution path. That makes possible what traditional languages cannot do: time-travel debugging, cross-machine session replay, and production failures that can be reproduced locally, line by line.

Wax is designed to embed into host applications for game development and UI frameworks, providing a safe, high-performance execution environment where every run is deterministic and every recorded frame is reconstructable.

What Wax Makes Possible#

Record and Replay

Record a session on one machine and replay it perfectly on another. When a user encounters a bug, you don’t get a stack trace and a vague description. You get the exact recorded execution that caused it. Load that recording on your development machine and you’re debugging their session, not a reproduction attempt.

Time-Travel Debugging

Step forward and backward through execution. Made a change and want to see how the program got to a certain state? Rewind. Missed the moment a value changed? Go back. The entire execution history is navigable because every frame’s state can be reconstructed.

Low-Cost Recording

Recording adds work: the runtime saves required inputs and periodically creates recording keyframes. Wax keeps that cost low by using frame boundaries as natural keyframe points and excluding short-lived nursery objects from keyframes. Creating a keyframe piggybacks on work the garbage collector already performs at frame end, so it is mostly a bulk copy of the retained heap and runtime side tables rather than a second object trace. If 90% of a frame’s allocations do not survive promotion, none of those objects enter the keyframe. Supported native applications can also move keyframe processing onto a background thread. Recording cost is concentrated at frame boundaries and scales with retained state and recorded input.

Safe Embedding

Wax is built to live inside other programs. The host boundary is explicit and controlled: no raw pointers cross the boundary, no callbacks from Wax into the host, all data is copied or passed through typed opaque handles. The host controls frame boundaries, object lifetimes, and resource limits. Embedding Wax doesn’t mean trusting Wax.

How Wax Achieves This#

The capabilities above aren’t features bolted onto an existing language design. They emerge from constraints built into the language itself:

Deterministic Execution

Wax keeps host-facing execution single-thread-affine and eliminates sources of non-determinism. Restricted parallel kernels may execute on runtime workers only when their resources and effects are statically isolated; their observable result is independent of worker count and scheduling. There are no data races, no platform-dependent behavior, and no hidden state. The same inputs always produce the same observable result.

Frame-Based Memory Model

Execution is organized into discrete frames defined by the host (a render frame, an HTTP request, a simulation tick). Memory is managed by a hybrid garbage collector with nursery promotion, so short-lived allocations are reclaimed cheaply at frame boundaries without manual annotation.

Explicit Host Boundary

All communication between Wax and the host is declared: host fn for functions the host provides, api fn for Wax functionality exposed to the host. Data crossing the boundary is copied or serialized. The host never gets raw pointers to Wax memory, and Wax never holds raw pointers to host memory.

Design Principles#

Determinism Over Convenience

Where other languages might allow flexible memory models or platform-dependent behavior for ergonomics, Wax chooses predictability. Every language feature is evaluated against the question: “Does this preserve deterministic execution and replayability?”

Write What Runs

Code should be straightforward to reason about at a glance. No implicit type conversions, no method overloading with complex resolution rules, no hidden allocations. What you read is what executes.

Sharp Knives, No Footguns

Wax gives you low-level memory control and direct host integration, but with guardrails. You can write high-performance code without the classes of bugs (use-after-free, null dereference, data races) that make low-level programming dangerous.

Zero-Cost Abstractions

High-level features like generics, constraints, and iterator pipelines compile down to code as efficient as hand-written loops. You don’t pay runtime cost for expressiveness.

Use Cases#

Wax is designed for host-driven environments where precision and reproducibility are critical:

Game Development

Deterministic execution enables lockstep networking, perfect replays, and session recording. Time-travel debugging lets you step through gameplay frame by frame. When a player reports a bug, you can debug their exact session.

UI Frameworks

The state system is built for UI: declare per-call-site state with lifecycle hooks. Frame-based execution maps naturally to render passes. Snapshot and replay capabilities enable visual regression testing and state inspection.

Simulations

Scientific and engineering simulations require reproducibility. Wax guarantees that a simulation run today will produce identical results to the same run next year, on different hardware, with the same inputs.

Sandboxed Extensibility

When your application needs user-provided logic (mods, plugins, automation scripts), Wax provides a safe execution environment with controlled resource access and no ability to escape the sandbox.

Performance Target#

Wax targets approximately 75% of native C performance for compute-bound code. The combination of static typing, nursery-promoting GC, and zero-cost abstractions makes this achievable while maintaining safety and determinism.

Language Tour: The Basics#

Welcome to Wax! This tour will walk you through the fundamental building blocks of the language. It assumes you’ve read the Overview and are ready to see what Wax code looks like.

The examples in this chapter assume these ordinary stdlib imports:

import Debug from Wax;
import List from Wax;

Hello, World!#

Like any good tour, we’ll start with the simplest program: printing a message.

api fn Main() {
    Debug.Log("Hello, World!");
}

This example defines a function named Main that, when called, prints the string “Hello, World!”. We mark it api so that the host application can see it and invoke it.

Declaration Documentation#

A documentation block begins with /** and supplies plain text for the named declaration immediately following it. Indentation and a single line break may separate the block from the declaration; a blank line or another comment leaves the block unattached. Unattached blocks are ignored.

/**
 * Starts a new game for the selected player.
 */
api fn StartGame(string player) { }

The optional leading * decoration and common indentation are removed from the stored text. Documentation is plain text: @ words and Markdown punctuation have no special meaning. /**/ and /*** ... */ banners remain ordinary block comments; use /** */ for an empty documentation block.

Variables, Constants, and Types#

Wax is a statically-typed language, meaning every variable has a known type at compile time.

You can declare variables using an explicit type annotation or let the compiler infer the type using the var keyword.

// Explicitly typed variable
string message = "This is a string.";

// Type is inferred from the assigned value (string)
var inferredMessage = "This is also a string.";

// Variables are mutable by default
int counter = 0;
counter = counter + 1; // counter is now 1

For values that should not change, you can declare them as constants using the const keyword. Constants must be assigned a value when declared and cannot be changed later.

const float Pi = 3.14159f;
// Pi = 3.0; // This would cause a compile error

Primitive Types & Literals#

Wax comes with a standard set of primitive types for handling numbers, text, and logic.

• Integers: For whole numbers. Wax supports various sizes and their unsigned counterparts. We support exact type sizes or more traditional integer type names.

// Signed integers
sbyte   // 8-bit signed  (alias: int8)
short   // 16-bit signed (alias: int16)
int     // 32-bit signed (alias: int32)
long    // 64-bit signed (alias: int64)

// Unsigned integers  
byte    // 8-bit unsigned  (alias: uint8)
ushort  // 16-bit unsigned (alias: uint16)
uint    // 32-bit unsigned (alias: uint32)
ulong   // 64-bit unsigned (alias: uint64)

Example:

int decimal = 42;
long bigNumber = 900_000_000L; // underscores can be used for visual separation
uint positiveOnly = 100u;
int32 hexValues = 0xff;
int32 binaryValues = 0b10_010101;

• Floating-Point Numbers: For numbers with fractional parts.

  float singlePrecision = 3.14f;       // 32-bit
  double doublePrecision = 3.14159265; // 64-bit
  

• Booleans: For true/false logic.

  bool isComplete = true;
  bool hasErrors = false;
  

• Strings and Characters: For text. Strings are UTF-8 encoded and support interpolation, while characters represent a single UTF32 code point.

  char letter = 'A';
  char emoji = '😀';
  
  string greeting = "Hello";
  string name = "Wax";
  string interpolated = "You can write $name code like this: ${1 + 1}"; // "You can write Wax code like this: 2"
  

Basic Operators#

Wax uses familiar operators for common operations.

• Arithmetic: +, -, *, /, % (modulo)

  int sum = 10 + 5;      // 15
  int difference = 10 - 5; // 5
  int product = 10 * 5;    // 50
  int quotient = 10 / 5;   // 2
  

  Note: Wax widens implicitly only when no data can be lost, meaning a smaller integer to a larger one (int to long), or float to double. Crossing between the integer and floating-point domains, or narrowing, always requires an explicit cast.

• Comparison: == (equals), != (not equals), <, >, <=, >=

  bool areEqual = (5 == 5); // true
  bool isGreater = (10 > 5); // true
  

• Logical: && (and), || (or), ! (not)

  bool result = (isComplete && !hasErrors); // true
  

Control Flow#

You can control the execution path of your code with conditional statements and loops.

• if-else Statements

  int score = 85;
  if (score > 90) {
      Debug.Log("Grade: A");
  } 
  else if (score > 80) {
      Debug.Log("Grade: B");
  }
  else {
      Debug.Log("Grade: C or lower");
  }
  

• for Loops

  // A traditional C-style for loop
  for (int i = 0; i < 5; i++) {
      Debug.Log("Loop iteration: $i");
  }
  

• foreach Loops

  The foreach loop is the idiomatic way to iterate over collections. It uses a special “payload” syntax (|item|) to access each element.

  List<string> names = new List<string>();
  names.Add("Alice");
  names.Add("Bob");
  names.Add("Charlie");
  
  foreach (names) |name| {
      Debug.Log("Hello, $name!");
  }
  
  // You can also get the index
  foreach (names) |name, index| {
      Debug.Log("$index: $name");
  }
  

• Deterministic parallel Kernels

  A parallel statement applies a restricted, allocation-free kernel to a half-open index range. Its aligned resources are preflighted before any iteration begins, and the statement joins synchronously.

  parallel (0, destination.size) : (
      readonly int32 value from source,
      out int32 result from destination,
  ) |index| {
      result = value + index;
  }
  

Functions#

Functions are reusable blocks of code that perform a specific task. You can define them with parameters and a return value.

// A function that takes two integers and returns their sum.
// The return type is specified after the colon.
fn Add(int a, int b) : int {
    return a + b;
}

// A function with no return value (implicitly returns void).
fn Greet(string name) {
    Debug.Log("Welcome, $name!");
}

// Calling the functions
int result = Add(10, 20); // result is 30
Greet("developer");       // Prints "Welcome, developer!"

Primitives and Literals#

Before you can build complex structs and classes, you need to understand the fundamental building blocks provided by the language. Primitive types are the simplest types, representing raw data like numbers, boolean values, and characters. A literal is how you write a fixed value directly in your source code.

Boolean (bool)#

The bool type represents a logical value and has only two possible literals: true and false.

bool isComplete = true;
bool hasErrors = false;

if (isComplete && !hasErrors) {
    // ...
}

Numeric Types and Literals#

Wax provides a standard set of integral and floating-point types for numeric data.

Integer Types#

Integer types represent whole numbers. They can be signed (positive or negative) or unsigned (positive only).

Integer Literals You can write integer literals in several formats. By default, a numeric literal is treated as an int. You can use suffixes to specify a different type.

• Decimal: 101
• Hexadecimal: 0x65 (prefix 0x)
• Binary: 0b01100101 (prefix 0b)

For readability, you can use an underscore _ as a separator anywhere within a numeric literal.

// Using suffixes to specify type
uint unsignedInt = 101u;
long longInt = 101l;
ulong unsignedLong = 101ul;

// Underscores can be placed anywhere for readability.
long bigNumber = 1_000_000_000l;
int hexValue = 0xDE_AD_BE_EF;
int binaryValue = 0b0101_0101;

Floating-Point Types#

Floating-point types represent numbers with fractional parts.

Floating-Point Literals Literals with a decimal point are treated as double by default. Use the f suffix for a float.

double pi_d = 3.14159; // Defaults to double
float  pi_f = 3.14159f; // Suffix 'f' makes it a float

double scientific = 1.23e4; // Scientific notation (1.23 * 10^4)

Type Aliases#

For clarity and compatibility with other systems, Wax provides explicit size-based aliases for the primitive numeric types. These can be used interchangeably with the standard names.

// These declarations are equivalent.
int a = 10;
int32 b = 10;

Numeric Promotion and Casting#

To prevent accidental data loss, Wax treats numeric conversions differently for literals and variables.

• Literal Promotion (Implicit): A numeric literal without a type suffix (e.g., 123) can be implicitly assigned to a larger numeric type if the value fits without any loss of data. The compiler can verify this at compile time.

• Implicit Widening: When a value is used in a context that expects a larger type within the same domain, the compiler automatically promotes it. Integer-to-wider-integer (int to long, byte to int, etc.) and float to double are always safe, because no data can be lost, so no cast is required. This applies to assignments, binary operations, and function arguments.

• Explicit Casting (Cross-Domain or Narrowing): Converting between different numeric domains (integer ↔ floating-point) or narrowing to a smaller type always requires an explicit cast. Wax provides three operators for this, each with a different safety guarantee.

  • as (Truncating Numeric Cast): Integer narrowing keeps the destination-width low bits. Floating-point to integer conversion first truncates the fractional part toward zero, then saturates to the destination range: values above or below the range become its maximum or minimum, and NaN becomes zero. The conversion never traps.
  • as? (Safe, Nullable Cast): Performs a safe conversion. If the conversion would result in data loss (e.g., the value is out of range), it returns null. This is the ideal operator for safely validating or handling data from external sources.
  • as! (Safe, Panicking Cast): Performs a safe conversion. If the conversion would result in data loss, the program will panic. Use this when you are certain a value should fit, and a failure represents a critical bug that should halt execution.

// --- Literal Promotion ---
long myLong = 123; // OK: Implicitly promotes 'int' literal.

// --- Variable Casting Examples ---
long bigValue = 3_000_000_000l;
float pi = 3.14f;

// Truncating 'as'
int truncated = bigValue as int; // Value wraps around, result is -1294967296
int truncatedFloat = pi as int;  // Value is truncated, result is 3
int saturatedFloat = 1.0e30 as int; // Value saturates, result is 2147483647

// Safe 'as?' - Returns null on data loss
int? noFit = bigValue as? int; // noFit is null
int? alsoNoFit = pi as? int;   // alsoNoFit is null
int? fits = 100l as? int;      // fits is an int? with value 100

// Safe 'as!' - Panics on data loss
// int panics = bigValue as! int; // PANIC! Value is out of range for int.
int mustFit = 100l as! int;    // OK: mustFit is 100

Type Safety in Operations#

Wax allows implicit widening within the same numeric domain. An int can be freely used alongside a long because widening an integer to a larger integer can never lose data. The same applies to float with double. The compiler inserts the promotion automatically.

However, conversions between integers and floating-point types always require an explicit cast, because these cross-domain conversions can change the representation of a value in subtle ways.

int a = 10;
long b = 20l;

// OK: 'a' is implicitly widened to long.
long c = a + b;

// Cross-domain requires explicit cast:
float f = 2.5f;
// double d = a + f;          // ERROR: int and float are different domains
double d = (a as double) + f; // OK: explicit cast to double

Characters (char)#

The char type represents a single 32-bit UTF-32 Unicode scalar value. Character literals are enclosed in single quotes.

A key safety feature of Wax is that a char is guaranteed to always be a valid Unicode value. The compiler will not allow you to create a char with an invalid or surrogate code point.

char letterA = 'A';

// Examples of Unicode escape sequences
char omega = '\u03A9';        // 4-digit hex, for Basic Multilingual Plane
char grinningFace = '\u{1F600}'; // Variable-length hex, for full Unicode range
char musicalG = '\U0001D11E';   // 8-digit hex, for full Unicode range

Escape Sequences#

Wax supports the following escape sequences within char and string literals:

Strings (string)#

The string type is a reference type that represents a sequence of characters.

String Literals#

A standard string literal is enclosed in double quotes. It cannot contain unescaped newlines. They support all the same escape sequences as char literals.

string greeting = "Hello, World!";
string empty = "";

// Using escape sequences in strings.
string path = "C:\\Users\\Default\\";
string multiline = "Line 1\nLine 2";
string withOmega = "The symbol for Omega is \u03A9.";

String Interpolation#

String literals support interpolation, so expressions can be embedded directly in the string.

• $identifier: Embeds the value of a variable.
• ${expression}: Embeds the result of a more complex expression.

Interpolation renders user-defined values through ToStringBuffer and renders a null nullable value as the literal null.

To include a literal $ character, escape it with a backslash: \$.

string user = "Alex";
int score = 120;

// Simple interpolation
string message = "User: $user, Score: $score"; // "User: Alex, Score: 120"

// Expression interpolation
string bonus = "Next level at ${score + 80} points."; // "Next level at 200 points."

string? missing = null;
string absent = "Value: $missing"; // "Value: null"

// Escaping the dollar sign
string price = "The cost is \$${score}."; // "The cost is $120."

Raw and Multiline Strings#

For strings that contain newlines or many special characters, you can use a raw string literal. A raw string is enclosed in three or more double quotes.

Raw strings can contain newlines and do not process most escape sequences (like \n or \\). However, they still support string interpolation.

// A simple multiline string
string poem = """
    The rose is red,
    The violet is blue,
    Wax is awesome,
    And so are you.
    """;

// Interpolation works the same way.
string report = """
    Report for: $user
    -------------------
    Final Score: $score
    """;

// You can use more quotes to allow """ inside the string.
string doc = """"
    This string can contain """, which is useful for examples.
    """";

Null Safety#

Wax is a null-safe language, which means the compiler helps you prevent errors that arise from trying to use a null value. Any type that is not explicitly marked as nullable cannot hold the null value.

To declare a nullable type, you append a ? to the type name.

• Nullable reference types (string?) have no size overhead at runtime.
• Nullable value types (int?, Point?) will be larger, as they must store an additional boolean flag.

string requiredText = "This can't be null.";
string? optionalText = null; // This is allowed.

int requiredInt = 10;
int? optionalInt = null; // This is also allowed.

Nullable Equality#

Two nullable values of the same type can be compared with == and != when the underlying type is a numeric primitive, bool, an enum, opaque, string, or a reference type. Nullable equality currently requires the operands to have the same nullable type exactly, including for reference types; for example, Base? and Derived? are not comparable with each other.

Nullable equality first compares the null state. Two null values are equal, and a null value is not equal to a non-null value. If both operands have values, Wax compares primitive, enum, opaque, and string values using the underlying type’s normal equality rule. For other reference types, it compares references.

int? a = null;
int? b = null;
int? c = 42;
int? d = 42;

bool bothNull = a == b;      // true
bool oneNull = a == c;       // false
bool sameValue = c == d;     // true

Safely Accessing Nullable Values#

Because a nullable variable might be null, Wax requires you to safely handle that possibility before you can use its value.

A direct comparison of a nullable local or value parameter with null also refines reads on the proven non-null path. The declaration remains nullable and assignments still target its original storage; assigning it ends the refinement. The fact can continue after an if when the null path exits, including through return, throw, panic, or unreachable.

fn Length(string? text) : int32 {
    if (text == null) {
        return 0;
    }
    return text.length; // 'text' is known non-null here
}

This refinement is intentionally limited to direct local == null and local != null checks. It does not apply to fields or other access paths, to ref/out or captured storage, or across assignment and loop joins where the value may have changed. A refined nullable value type is a read-only snapshot: its fields and elements can be read, but member writes and method calls require an explicit payload binding or ! unwrap so mutation cannot silently target a compiler-owned copy.

Safe Unwrapping with if#

The most common way is with the if payload syntax, which unwraps the value into a new, non-nullable variable that is only available inside the if block.

string? maybeName = GetUserName();

if (maybeName) |name| {
    // Inside this block, 'name' is a non-nullable string.
    Debug.Log("Hello, $name!");
}
else {
    // This block runs if maybeName was null.
    Debug.Log("Hello, guest!");
}

Conditional Unwrapping with Ternary#

For a more concise conditional, you can use the ternary expression with payload capture. It unwraps the nullable value and binds it for the “true” branch of the expression.

string? maybeName = GetUserName();

string greeting = maybeName ? |name|
    "Hello, $name!"
    : "Hello, guest!";

Providing a Default with ??#

You can provide a default value using the null-coalescing operator ??.

// If maybeName is null, use "guest" instead.
string name = maybeName ?? "guest";

Safe Chaining with ?.#

The null-conditional operator ?. safely accesses members, indexes elements, or invokes delegates on a nullable variable. If the variable is null, the expression short-circuits and returns null.

string? text = GetSomeText();

// Member access: ?.field
int32? length = text?.length;

// Chained calls: if any part is null, the result is null.
char? firstChar = text?.ToUpper()?.FirstChar();

// Element access: ?.[index]
int32[]? items = GetItems();
int32? first = items?.[0];

// Invocation: ?.(args)
fn(string) : int? parser = GetParser();
int? parsed = parser?.("42");

Forcing an Unwrap with !#

If you are certain that a nullable variable is not null, you can use the null-forgiving operator ! to access its value directly. Be careful: if the value is null at runtime, this will cause a panic.

string? maybeValue = "I am definitely not null";

// This is safe because we know the value is not null.
string value = maybeValue!;

// This would cause a panic at runtime.
string? nullValue = null;
string badAccess = nullValue!; // PANIC!

Other Fundamental Concepts#

Beyond simple literals, several other keywords and types are fundamental to the language.

Type Inference with var#

You can use the var keyword to declare a variable without explicitly stating its type. The compiler will infer the type from the value assigned to it. This is particularly useful for keeping code concise when the type is obvious.

var i = 10;          // Inferred as int
var pi = 3.14;       // Inferred as double
var name = "Alex";   // Inferred as string
var isDone = true;   // Inferred as bool

Compile-Time Constants with const#

Use the const keyword to declare a value that is fixed at compile time. The value of a constant cannot be changed at runtime, and the compiler will substitute the value wherever it is used.

The expression used to define a const must itself be resolvable at compile time. This includes:

• Literals (123, "hello", true).
• Other const values.
• Enum members.
• sizeof(T) expressions.
• Expressions combining the above, such as mathematical operations or string interpolation.

const int MaxUsers = 100;
const int MaxAdmins = 10;
const int TotalAccounts = MaxUsers + MaxAdmins; // Math on consts

const string AppName = "My Awesome App";
const string Version = "1.0";
const string AppTitle = "${AppName} v${Version}"; // String interpolation

flags Permissions { case Read=1; case Write=2; }
const Permissions ReadWrite = Permissions.Read | Permissions.Write; // Enum ops

The object Type#

object is the universal base type for all reference types. This means any instance of a class, string, or other reference type can be assigned to a variable of type object. It is the root of the class hierarchy.

object obj1 = new MyClass();
object obj2 = "a string is a reference type";

The void Type#

The void type is a special type that indicates the absence of a value. You cannot declare a variable of type void, but it is used as the return type for functions that do not return a value.

fn LogMessage(string message) : void {
    // This function performs an action but does not return a value.
}

The json Type#

The json type is a first-class dynamic data type for working with structured data. JSON values can represent nulls, booleans, numbers, strings, arrays, and objects. The json type is covered in detail in its own chapter.

json config = { name: "MyApp", version: 1, debug: true };
json items = [1, 2, 3];
string name = config.name!;

The opaque Type#

The opaque type represents an unvalidated handle to a resource managed by the host application. Wax can store and pass around opaque values but cannot inspect or manipulate them. This is the standard way to reference host-side resources like window handles, file handles, or graphics resources across the host boundary.

host fn CreateWindow(int32 width, int32 height) : opaque;
host fn DestroyWindow(opaque handle);

Compiler-Known Algebraic Types#

Wax provides compiler-known value types for common graphics, math, and simulation domains. Lowercase type spellings are reserved, import-free built-ins. Every user-declared type must begin with an uppercase letter. Uppercase nominal type names use ordinary lookup and must be declared in the current source or imported. Uppercase declarations that back lowercase built-ins inside the compiler’s built-in module are implementation details and cannot be imported by application modules.

Vector types: float2, float3, float4 represent 2D, 3D, and 4D floating-point vectors.

Matrix types: float3x2, float3x3, float4x4 represent common transformation matrices.

Color types: color8, color16, color32 are reserved, import-free built-ins representing colors at different bit depths (8-bit per channel RGBA, 16-bit per channel, and 32-bit float per channel).

Rotation shape type: quaternion is a reserved lowercase algebraic keyword representing 3D rotations.

Domain types: timespan, angle, timepoint are reserved, import-free built-ins representing durations, angular values, and monotonic clock samples.

SIMD types: the width-explicit vector families such as int8x16, uint32x4, and float64x2 are reserved lowercase algebraic keywords.

Import the uppercase stdlib nominal type before use:

import StringBuilder from Wax;

Lowercase stringbuilder has no special type meaning and is available as a normal identifier.

Parameterless Construction#

Primitive types expose a public parameterless constructor through their capitalized Wax wrapper declaration. The constructor is defined in the standard library and produces the primitive’s zero value, so generic code can construct a primitive through an ordinary constructor constraint:

int32 direct = new int32(); // 0

constraint Constructable {
    constructor();
}

fn Create<T>() : T where T is Constructable {
    return new T();
}

int32 fromGeneric = Create<int32>(); // 0

This is constructor invocation and is distinct from default: default never invokes user code, while new T() is permitted only when the selected type has a matching parameterless constructor.

The default Keyword#

The default keyword is an expression that returns the type’s canonical zero value. It never allocates an object, invokes user code, or supplies arguments to a constructor. Its behavior is strictly defined to ensure type safety.

• For numeric types: Returns 0.
• For bool: Returns false.
• For char: Returns \0.
• For nullable types (T?): Returns null.
• For json: Returns the JSON null value.
• For enums: If a case is explicitly marked with default, returns that case. Otherwise, returns the case whose value is 0, if one exists. If neither exists, the enum type is not compatible with default, and using it is a compile-time error.

  enum Color {
      default case Black; // This case is the default
      case Red;
      case Blue;
  }
  Color c = default; // c is Color.Black
  

• For value-type structs: Returns an all-zero instance when that bit pattern is a valid value for every instance field. A struct containing a non-nullable reference, or an enum without a valid zero/default case, is not compatible with default.
• For reference types: A nullable reference returns null. A non-nullable reference is not compatible with default; default does not invoke a parameterless constructor. Use new MyClass() when construction is intended.

// --- Valid uses of default ---
int i = default;         // i is 0
string? s = default;     // s is null

struct Point { float x; float y; }
Point p = default;       // p is a Point where p.x=0.0f, p.y=0.0f

enum State { case Idle = 0; case Running = 1; }
State state = default;   // state is State.Idle

class Player { constructor() { /* ... */ } }
Player player = new Player(); // Invokes the parameterless constructor

// --- Invalid uses of default ---
// string name = default; // ERROR: string is a non-nullable reference.

// enum Status { case Ok = 1; case Error = 2; }
// Status s = default; // ERROR: Status has neither a default case nor a zero-valued case.

// struct User { string name; }
// User u = default; // ERROR: User has no valid all-zero value.

Detailed Numeric Parsing Errors#

Integer and floating-point types provide ParseDetailed when a caller needs to distinguish failures. It throws ParseError, whose readonly kind and position fields identify the failure and its UTF-8 byte offset. The public ParseErrorKind cases are Empty, NoDigits, InvalidCharacter, NegativeUnsigned, OutOfRange, and InvalidRadix. Overflow is always reported as OutOfRange; internal accumulator details are not exposed. Its message includes both the byte position and the public kind name.

The nullable Parse convenience remains appropriate when the reason does not matter.

Regular Expressions (Regex)#

Wax provides built-in regular expression support through the regex() operator. It creates a Regex object and has two forms depending on how the pattern is provided.

Regex, RegexOptions, and RegexError are ordinary uppercase stdlib types and require imports. The examples in this section assume:

import Regex from Wax;
import RegexOptions from Wax;
import RegexError from Wax;

Regex Literals#

When the pattern is known at compile time, use a /pattern/ literal inside regex(). The compiler validates the pattern during compilation, so an invalid pattern is a compile-time error rather than a runtime failure.

Regex digits = regex(/\d+/);
Regex email = regex(/[a-zA-Z]+@[a-zA-Z]+\.[a-zA-Z]+/);

// With flags
Regex caseInsensitive = regex(/hello/, RegexOptions.IgnoreCase);

// Invalid patterns are compile errors
// Regex bad = regex(/[unclosed/);  // ERROR: missing terminating ] for character class

Because the pattern is validated at compile time, no error handling is needed, and the Regex object is guaranteed valid.

Patterns inside / delimiters are raw, so backslashes are literal and \d means “digit” rather than an escape sequence. This avoids the double-escaping required in string literals.

String Literal Patterns#

You can also pass a string literal to regex(). The compiler validates it at compile time, just like a / literal:

Regex r = regex("\\d+");  // validated at compile time (note: double backslash in strings)

Dynamic Patterns#

When the pattern comes from a variable (user input, configuration, etc.), the compiler cannot validate it at compile time. In this case, regex() can fail at runtime, and you must use try/catch:

fn CreateRegex(string pattern) : Regex {
    return try regex(pattern) catch |e| {
        yield regex(/./);  // fallback
    };
}

Calling regex() with a dynamic string without try is a compile-time error. On failure it throws RegexError; message describes the syntax problem and the readonly position field is the UTF-8 byte offset in the original pattern.

Flags#

Pass RegexOptions as a second argument to regex():

Regex r = regex(/hello/, RegexOptions.IgnoreCase);

Inline modifier groups such as (?i) are not supported; flags are passed as the second argument only. The group forms the pattern syntax does accept are the non-capturing (?:...) and the lookarounds (?=...) / (?!...).

Available flags: IgnoreCase, Multiline (^/$ match line boundaries), Singleline (. matches newlines), FreeSpacing (ignore whitespace and # comments in pattern).

Operators in Wax#

Wax provides a familiar set of operators for performing arithmetic, logical, and other common operations. The language is designed to be predictable, so operator behavior is consistent and straightforward.

The examples in this chapter assume these ordinary stdlib imports:

import Debug from Wax;
import Dictionary from Wax;
import Error from Wax;

Operator Precedence#

Wax follows a standard operator precedence, similar to other languages in the C family. For example, multiplicative operators (*, /, %) have higher precedence than additive operators (+, -). Parentheses () can always be used to explicitly control the order of evaluation.

Standard Operators#

The following table lists the standard operators available in Wax, grouped by category.

Shift-Count Masking#

The shift operators << and >> are total: the shift count is masked to the operand’s bit width before shifting, so x << n and x >> n use n & 31 for a 32-bit operand and n & 63 for a 64-bit operand. Every count is well-defined, including counts greater than or equal to the width and negative counts. For example, x << 32 on a 32-bit value is x << 0, which is x. This behavior is identical on every backend.

Null-Related Operators#

Wax includes special operators for safely and concisely working with nullable types (T?).

Null-Conditional Operator: ?.#

The null-conditional operator accesses members, calls methods, or indexes elements on a nullable variable. If the variable is null, the expression short-circuits and evaluates to null instead of causing a panic.

The ?. operator supports three forms:

string? name = GetPlayerName(); // This might return null

// Member access: ?.field
int32? length = name?.length;

// Element access: ?.[index]
int32[]? numbers = GetNumbers();
int32? first = numbers?.[0];

// Invocation: ?.(args)
fn<(int32) : string>? formatter = GetFormatter();
string? result = formatter?.(42);

Note: A standalone ? is always the ternary operator (cond ? trueExpr : falseExpr). All null-conditional forms use ?. as the operator.

A ?. chain that ends in a call is also valid as a statement, where it means call if non-null, otherwise do nothing:

Logger? logger = GetLogger();
logger?.Write("started");        // void method: runs only when logger is non-null
logger?.Flush();                 // a non-void result is discarded, like `Flush();`

fn<()>? onTick = GetTickHandler();
onTick?.();                      // delegate form

In statement position a void callee is allowed, which is the only way to invoke one conditionally, and a non-void result is discarded exactly as it is for a plain foo();. A ?. chain that does not end in a call (logger?.name;) is rejected, because it computes a value nobody consumes. When the receiver is statically non-nullable the ?. is pointless and the compiler warns.

Null-Coalescing Operator: ??#

The null-coalescing operator provides a default value for a nullable type. It returns the left-hand operand if it’s not null; otherwise, it returns the right-hand operand.

string? playerName = GetConfiguredName(); // Might be null

// Provide a default value if playerName is null.
string displayName = playerName ?? "Guest";

The right-hand side may instead be a diverging bail term (throw, panic, or unreachable), which yields no value. The result is then the left operand’s non-null type, and the null branch bails out instead of producing a fallback. This is the single-value, expression-position counterpart to guard:

Player p = playerName ?? throw new Error("no name");   // in a `throws` fn
Player p = playerName ?? panic("no name");

Null-Forcing (Panic) Operator: !#

The postfix ! operator is used to assert that a nullable value is not null. It unwraps the value, returning the non-nullable type. If the value is null at runtime, the program will panic. This should only be used when you are absolutely certain the value cannot be null.

string? requiredValue = GetValueFromDatabase();

// I am certain this value exists. If it doesn't, it's a critical error.
string unwrappedValue = requiredValue!; // Panics if requiredValue is null.

Type-Related Operators#

Wax provides several operators for testing and converting types.

Type Testing Operator: is#

The is operator is a purely boolean operator. It performs a runtime check to see if an object is of a certain type and returns true or false.

object shape = GetShape();
bool isCircle = (shape is Circle); // isCircle is true or false

if (isCircle) {
    // We know the shape is a Circle, but we still need to cast it.
    var c = shape as! Circle;
    Debug.Log("It's a circle with radius ${c.radius}");
}

Type Casting Operators: as, as?, as!#

These operators handle converting an object from one type to another.

• as (Compile-Time Safe Cast / Truncating Numeric Cast): For reference types, as performs conversions that the compiler can guarantee are safe, such as upcasting to a base class or interface. Integer narrowing keeps the destination-width low bits. Floating-point to integer conversion truncates toward zero and then saturates to the destination range, with NaN becoming zero; it never traps. See the Numeric Promotion and Casting section for details.

  Dog myDog = new Dog();
  Animal myAnimal = myDog as Animal; // Safe upcast
  

• as? (Safe Dynamic Cast): This performs a runtime check. If the cast is successful, it returns the re-typed object. If it fails, it returns null. This is the recommended operator for downcasting when the result of the cast is needed as a value.

  fn Process(Animal animal) {
      Dog? maybeDog = animal as? Dog;
      if (maybeDog) |d| {
          // Safely use 'd' as a Dog
      }
  }
  

• as! (Forced Dynamic Cast): This performs a runtime check. If the cast is successful, it returns the re-typed object. If it fails, the program will panic. This should only be used when you are certain the cast will succeed and a failure represents a critical program error.

  Animal animal = GetDogFromDatabase(); // We are certain this is a Dog
  Dog myDog = animal as! Dog; // Panics if it's not a Dog
  

Operator Overloading and Indexers#

A core design principle of Wax is simplicity and predictability. For this reason, custom operator overloading is not supported for user-defined types. You cannot define custom behavior for operators like +, -, ==, etc. on your own class or struct.

Built-in Vector and Matrix Overloads#

The only exception to this rule is for the built-in mathematical vector and matrix types (e.g., float2, float3, float4, float4x4). These types have standard operator overloads for common mathematical operations.

var a = new float2(1, 2);
var b = new float2(3, 4);

// This works because float2 has a built-in operator overload for '+'.
var c = a + b; // c is (4, 6)

Custom Indexers []#

While you cannot overload most operators, Wax does allow user-defined types to implement custom indexers. An indexer defines what myObject[index] means for your type, and is the closest Wax comes to custom operator overloading. A type can define at most one indexer, which can have a getter, a setter, or both, following the same rules as properties.

Indexers are declared with get this(...) and set this(...), using the same syntax as properties. The getter’s parameters define the index signature, and its return type defines the element type; the setter takes the same index parameters plus a trailing value parameter.

class Scoreboard {
    private Dictionary<string, int> scores;

    constructor() { this.scores = new Dictionary<string, int>(); }

    // Custom indexer implementation
    public get this(string playerName) : int {
        return try this.scores[playerName] catch { yield 0; };
    }

    public set this(string playerName, int value) {
        this.scores[playerName] = value;
    }
}

var board = new Scoreboard();
board["Alice"] = 100; // Uses the 'set' indexer
int score = board["Alice"]; // Uses the 'get' indexer

Control Flow#

Control flow statements allow you to direct the execution path of your program based on conditions and loops. Wax provides a standard set of control flow structures that will be familiar to developers coming from languages like C#, Java, or C++.

Conditional Execution: if and else#

The if statement executes a block of code only if a specified condition is true. It can optionally be followed by else if and else blocks to handle other cases.

int score = 85;

if (score >= 90) {
    Debug.Log("Grade: A");
} 
else if (score >= 80) {
    Debug.Log("Grade: B");
}
else {
    Debug.Log("Grade: C or lower");
}

if with Payload Unwrapping#

The if statement can also be used to safely unwrap nullable types or perform type tests. If the condition is successful, the unwrapped value is available inside the if block in a new, non-nullable variable.

string? maybeName = GetUserName();

// The 'if' statement checks if maybeName is not null.
// If it isn't, the value is unwrapped into the 'name' variable.
if (maybeName) |name| {
    Debug.Log("Hello, $name!"); // 'name' is a non-nullable string here.
}

// This also works for type testing with reference types.
object data = GetSomeAnimal();
if (data is Dog) |dog| {
    // 'dog' is a non-nullable variable of type Dog here.
    Debug.Log("The dog's name is ${dog.name}.");
}

Several conditions can be combined in one if. The comma-separated list behaves like && (left-to-right, short-circuit): the body runs only when every condition holds, and a later condition is not evaluated once an earlier one fails. Payload slots map to the conditions positionally. A plain boolean condition gates without a slot, and _ discards a slot so a later condition can still be bound.

// Both must be non-null; a0 and b0 are bound in the body.
if (firstUser, secondUser) |a0, b0| {
    Debug.Log("$a0 and $b0");
}

// A bool guard just gates (no slot); the nullable is unwrapped.
if (maybeName, isReady) |name| {
    Debug.Log("Hello, $name!");
}

// `_` steps past a condition to bind a later one.
if (isReady, maybeName) |_, name| {
    Debug.Log("Hello, $name!");
}

Naming a non-nullable (e.g. a bool) slot is an error, because there is nothing to unwrap. Each condition is evaluated in the enclosing scope, so a condition cannot reference a binding introduced by an earlier condition (keep those nested).

guard: capture-or-bail#

guard shares the if condition-list and payload syntax, but with two differences: the payload binds downward into the enclosing scope (so the unwrapped value is live after the statement, flat, with no nesting), and the mandatory else runs when the gate fails and must diverge (return, break, continue, throw, panic, unreachable, yield, or a block / if-else composed of those; yield is diverging inside a catch/pipeline). There is no if-style body, because the success continuation is the enclosing scope itself.

guard (maybeName) |name| else return;
Debug.Log("Hello, $name!");                 // `name` is non-null here

guard (firstUser, secondUser) |a, b| else { return; }   // both bindings escape
guard (hp > 10, target) |_, t| else return;             // `_` gates a bool; `t` binds
guard (hp > 10) else return;                             // boolean-only precondition

The binding is a snapshot (an unwrapped local copy), which is sound regardless of later mutation of the source. If the else can fall through, as in else { } or else { Log(); }, it is an error: the else must diverge.

The switch Statement#

The switch statement provides a clean way to compare a single value against a list of possible cases. In Wax, the value being switched on must be an integer type, char, enum, or string. More complex pattern matching is not supported.

Each case must be enclosed in curly braces {}, which creates a new scope.

enum Status {
    case Pending;
    case Running;
    case Completed;
    case Failed;
}

Status currentStatus = GetStatus();

switch (currentStatus) {
    case Status.Pending: {
        Debug.Log("The task is waiting to start.");
    }
    case Status.Running: {
        Debug.Log("The task is in progress.");
        if (NeedsImmediateAttention()) {
            Debug.Log("Breaking out of case block early.");
            break; // Optional: exits the current case block.
        }
        // ... more processing ...
    }
    case Status.Completed: {
        Debug.Log("The task finished successfully.");
    }
    default: {
        Debug.Log("Unknown status.");
    }
}

Note: Each case must be enclosed in curly braces {}, which prevents accidental “fall-through.” The break statement is optional and can be used to exit a case block early.

Advanced switch Features#

The switch statement supports more advanced patterns for greater flexibility.

• Multiple Cases: You can specify multiple case expressions for a single block, separated by commas.
• when Clause: You can add a when clause to a case to provide an additional boolean condition.

char input = GetInputChar();

switch (input) {
    // Multiple cases for one block.
    case 'y', 'Y': {
        Debug.Log("Affirmative.");
    }

    case 'n', 'N': {
        Debug.Log("Negative.");
    }

    // A case with an additional 'when' condition.
    case 'd': when (IsDebugModeEnabled()) {
        Debug.Log("Entering debug mode.");
    }

    default: {
        Debug.Log("Unknown command.");
    }
}

Ternary Expression#

For simple conditional assignments, you can use the ternary expression (? :) as a compact alternative to an if-else block. It evaluates a condition and returns one of two expressions.

int score = 75;
string result = (score > 50) ? "Pass" : "Fail";
// result is "Pass"

// Like 'if', the ternary expression also supports payload unwrapping.
string? maybeName = GetName();
string displayName = maybeName ? |name| name : "Guest";

// Either arm may instead be a diverging bail term (`throw` / `panic` /
// `unreachable`) that yields no value, and the result takes the other arm's type.
int port = config.HasPort ? config.Port : throw new ConfigError("no port");

Loops#

Loops are used to execute a block of code repeatedly.

The for Loop#

The for loop is ideal when you know how many times you want to iterate. It consists of an initializer, a condition, and an iterator.

for (int i = 0; i < 5; i++) {
    Debug.Log("Current number is: $i");
}

The while Loop#

The while loop executes as long as a specified condition remains true. The condition is checked before each iteration. Like the if statement, while also supports payload syntax to safely unwrap nullable values.

// A simple while loop
int countdown = 3;
while (countdown > 0) {
    Debug.Log(countdown);
    countdown = countdown - 1;
}
Debug.Log("Liftoff!");

// A while loop with payload unwrapping, useful for linked lists.
Node? currentNode = GetLinkedListHead();
while (currentNode) |node| {
    ProcessNode(node);
    currentNode = node.next; // Loop continues as long as .next is not null.
}

The do-while Loop#

The do-while loop is similar to the while loop, but the condition is checked after the block executes. This guarantees that the loop body will run at least once.

// This loop will execute once, even though the condition is false.
int i = 10;
do {
    Debug.Log("This will print once.");
    i++;
} while (i < 5);

The foreach Loop#

The foreach loop is the most convenient way to iterate over all elements in a collection. It uses a special “payload” syntax (|item|) to access each element.

import List from Wax;

var names = new List<string>();
names.Add("Alice");
names.Add("Bob");
names.Add("Charlie");

// Iterate through each name in the list.
foreach (names) |name| {
    Debug.Log("Hello, $name!");
}

// You can also get the index of the current element.
foreach (names) |name, index| {
    Debug.Log("User $index is $name.");
}

Keyed Iteration with key#

In a state foreach loop (see the State System chapter), each iteration maintains its own persistent state. By default, state is keyed by index, but if items can be reordered, you should provide an explicit key expression with the key clause. This ensures state follows the identity of each element rather than its position.

The key clause goes after the payload capture, before the body. The expression is evaluated per iteration with the payload variable(s) in scope, and it can be a field access, method call, external function call, or any inline expression producing a Hashable value.

state foreach (users) |user| key user.id {
    state bool isExpanded = false;
    // Each user's isExpanded state is tied to their id, not their position.
}

The key clause is only valid on state foreach loops. See the State System chapter for full details.

Deterministic Parallel Kernels#

A parallel statement applies one restricted kernel to each logical index in the half-open interval [start, end). The optional payload binds the current index.

parallel (0, destination.size) : (
    readonly int32 value from source,
    out int32 result from destination,
) |index| {
    result = value * scale + index;
}

Each binding has the form mode Type name from source, where mode is:

• readonly: read the element at the current index;
• ref: read and then write back the current element;
• out: assign and write back the current element.

Registered sources are arrays, List<T>, Span<T>, and ReadOnlySpan<T> when their mutability permits the selected mode. The source is a path, not an arbitrary producer expression. The collection itself is not visible inside the body; only the aligned element and registered read-only span capabilities are.

Before the first kernel invocation, the runtime validates the range, verifies that every aligned source covers end, and checks the complete alias set. Writable ranges must be disjoint from every distinct writable or read-only range; read-only ranges may overlap each other. Any failure panics before an iteration runs, so preflight never leaves a partially updated result.

The compiler admits only kernels whose effects are independent across logical indices. In particular, a kernel cannot allocate, read or write statics, call a host or API boundary, use dynamic/delegate dispatch, nest parallel, escape an error, or publish reference-bearing output. Captures are immutable data values. break and a return from the enclosing function cannot cross the kernel boundary. A continue at kernel-body level ends the current logical invocation; definite assignment requires every out binding to be assigned first. A continue inside a nested loop retains its ordinary loop meaning.

The statement is synchronous and joins all iterations before control continues. An implementation may execute the fixed kernel serially or on runtime workers; worker count, chunking, scheduling, and completion order do not change its observable result. Wasm executes the same semantics serially. Instrumented and profiled native builds also use the serial path so debugger and profiler state remain app-thread-owned.

Loop Control Statements#

You can alter the execution of a loop using the break and continue statements.

• break: Immediately terminates the innermost loop.
• continue: Skips the remainder of the current iteration and proceeds to the next one.

// An example using both break and continue.
for (int i = 0; i < 10; i++) {
    if (i % 2 == 0) {
        // Skip even numbers.
        continue;
    }

    if (i > 7) {
        // Stop the loop entirely if the number is greater than 7.
        break;
    }

    Debug.Log("Processing odd number: $i");
}
// Output:
// Processing odd number: 1
// Processing odd number: 3
// Processing odd number: 5
// Processing odd number: 7

Functions in Wax#

Functions are the primary building blocks for executable code in Wax. They can be declared at the top level of a file, as methods within a type, or defined anonymously as lambdas.

Functions are first-class values in Wax. They can be stored in variables, passed as arguments, and returned from other functions.

Function Declaration#

All functions are declared using the fn keyword, followed by the function’s name, a parameter list in parentheses (), an optional return type, and a body enclosed in curly braces {}.

// A simple function with no parameters that returns nothing (void is implicit).
fn DoSomething() {
    // ...
}

// A function with parameters and an explicit return type.
fn Add(int a, int b) : int {
    return a + b;
}

A Core Principle: No Overloading#

A fundamental design choice in Wax is that it does not support function overloading. This means that within a given scope (e.g., at the top level, or within a single type), you cannot declare multiple functions with the same name, even if they have different parameter lists.

This principle simplifies the language significantly by eliminating complex method resolution rules. A call to MyFunction(...) is therefore never ambiguous. To provide the flexibility that overloading offers in other languages, Wax relies on features like:

• Default Parameter Values: To simulate overloads with fewer arguments.
• Named Arguments: To provide clarity when calling functions with many parameters.
• Named Constructors: To provide multiple ways to initialize an object.

Function Parameters and Arguments#

Function signatures can be modified with several keywords and feature syntaxes to control how data is passed.

Default Parameter Values#

Parameters can be made optional by providing a default value. The default value itself can be any valid expression (including constants, function calls, or new expressions), which is evaluated only if the argument is not provided at the call site. When the argument is omitted, a fresh evaluation of the default expression is inlined at that call site, so a default such as new Point(0, 0) constructs a new object on each defaulted call rather than a single shared instance.

The default expression is type-checked once, at the declaration, in the function’s own scope (its using directives, imports, and enclosing generic type parameters), not in the scope of each caller. This has three consequences:

• An invalid default is reported exactly once, at the declaration, even if the function is never called or every call supplies the argument explicitly.
• The default resolves against the callee’s visibility, so it may name types the caller has not imported.
• The default is a standalone expression evaluated before parameters are bound, so it cannot reference other parameters or this.

A default may name the enclosing type’s or method’s generic type parameters; each instantiation substitutes them concretely:

struct Box<T> {
    public int32 tag;
    public constructor Tagged() { tag = 7; }
}

// `new Box<T>()` in the default resolves T per instantiation.
fn Pick<T>(int32 a, Box<T> b = new Box<T>.Tagged()) : int32 {
    return a + b.tag;
}

Pick<int32>(10);  // default builds a Box<int32>
Pick<string>(20); // default builds a Box<string>

As a general rule, once a parameter is given a default value, all subsequent parameters must also have default values.

// Valid: 'enabled' has a default, and it's the last parameter.
fn CreateEntity(string name, Point position = new Point(0, 0), bool enabled = true) {
    // ... function body
}

// Invalid: 'priority' is required but comes after 'retry', which has a default.
fn Configure(string id, bool retry = true, int priority) { // Error!
    // ...
}

However, there is one important exception to support common API patterns with trailing closures: a single, required function type parameter may appear as the last parameter in a list, even after parameters with default values.

// This is VALID due to the exception for a trailing function type.
fn PostNotification(string name, bool urgent = false, fn<() : void> onComplete) {
    // ... implementation ...
    onComplete();
}

// This allows for a very clean call-site using the trailing closure syntax.
PostNotification("UpdateComplete", .urgent = true) {
    Log("Notification posted successfully.");
};

Named Arguments#

To improve clarity, especially for functions with many parameters, you can call functions using named arguments. Arguments may then be given in any order, and the call site reads more clearly. You can mix positional and named arguments, but all positional arguments must come before any named arguments.

fn Configure(string id, int timeout, bool retry, float priority) {
    // ... function body
}

// Call-site examples:
Configure(.id = "task-123", .priority = 0.9, .retry = true, .timeout = 5000);
Configure("task-456", .retry = false, .priority = 0.5, .timeout = 10000); // Mixed
// Configure(.id = "task-789", 5000, .retry = false); // Error: Positional arg after named arg

Parameter Modifiers (ref, out)#

These keywords control how parameters are passed. ref and out are mutually exclusive.

ref: Passes the parameter by reference, allowing the function to modify the original variable. The argument must be initialized before the call.

out: Passes the parameter by reference. The function must assign a value to the parameter before it returns. The argument does not need to be initialized.

// Definition combining modifiers
fn ProcessData(ref int value, out string result) {
    value *= 2;        // Modifies the original caller's variable
    result = "Processed"; // Assigns to the caller's variable
}

// Call-site
int myValue = 10;
string myResult; // Does not need to be initialized for 'out'
ProcessData(ref myValue, out myResult);
// After the call, myValue is 20 and myResult is "Processed"

ref Returns#

Functions can return a reference to a value, allowing for direct modification of the original data source. This is an advanced feature for performance-critical scenarios.

class GameState {
    private int score;
    public fn GetScoreRef() : ref int {
        return ref this.score;
    }
}

var gameState = new GameState();
ref int currentScore = gameState.GetScoreRef();
currentScore += 100; // Modifies the score inside the 'gameState' object directly.

Contexts for Functions#

Top-Level Functions#

Functions declared outside of any type are known as top-level functions. They do not have access to an instance this and are useful for creating global helper routines.

internal fn CalculateDistance(Point a, Point b) : float {
    float dx = a.x - b.x;
    float dy = a.y - b.y;
    return Math.Sqrt(dx * dx + dy * dy);
}

Instance and Static Methods#

Functions declared inside a type (like a class, struct, or enum) are called methods.

Instance Methods: The default type of method. They have access to the this keyword, which refers to the specific object instance the method was called on.

Static Methods: Declared with the static keyword. They belong to the type itself, not an instance, and therefore do not have access to this. Top-level functions are conceptually similar to static methods as they are not associated with any instance.

class Calculator {
    // Instance method
    fn Add(int a, int b) : int { return a + b; }

    // Static method
    static fn GetHelp() : string {
        return "This is a calculator class.";
    }
}

// Calling an instance method requires an object.
var calc = new Calculator();
int sum = calc.Add(2, 3);

// Calling a static method is done on the type.
string help = Calculator.GetHelp();

Methods and Inheritance#

When working with classes, methods can participate in inheritance using special modifiers.

virtual: Marks a method in a base class, allowing it to be replaced by a derived class.

override: Provides a new implementation for a virtual member from the base class.

sealed: Placed on an override member, it prevents derived classes from overriding it further. It is only valid together with override.

abstract: Declares a method in an abstract class without an implementation. Any non-abstract derived class must provide an override.

abstract class Animal {
    // An abstract method that derived classes MUST implement.
    public abstract fn MakeSound() : string;
}

class Dog extends Animal {
    // We MUST provide an implementation for the abstract method.
    public override fn MakeSound() : string {
        return "Woof!";
    }
}

Generic Functions#

Functions in Wax can be generic, allowing them to operate on a variety of types in a type-safe way. Generic type parameters are declared in angle brackets <...> after the function name.

// A generic function that swaps two values of the same type.
fn Swap<T>(ref T a, ref T b) {
    var temp = a;
    a = b;
    b = temp;
}

// The compiler infers 'T' as 'int' at the call-site.
int x = 10;
int y = 20;
Swap(ref x, ref y); // x is now 20, y is now 10

Generic functions can also have constraints to require that a type parameter supports certain operations. For more details, see the Generics and Constraints section.

First-Class Functions and Lambdas#

Function Types#

A function’s signature, meaning its parameters and return type, defines its type. The primary way to define a function type is with the inline fn<...> syntax. The syntax inside the angle brackets (<>) is identical to the syntax for declaring a named function’s signature (its parameters, return type, and throws clause).

// A function that accepts a validator as a parameter.
fn ProcessInput(string data, fn<(string) : bool> validator) {
    if (validator(data)) { /* ... */ }
}

Lambda Expressions#

A lambda expression is a concise way to define an anonymous (unnamed) function using the => operator. In most cases, the compiler can infer the parameter types from the context.

// The compiler infers that 'a' and 'b' are ints from the 'add' variable's type.
fn<(int, int) : int> add = (a, b) => a + b;

// The compiler infers 'n' from the parameter the lambda is passed to.
fn KeepIf(int[] items, fn<(int) : bool> predicate) : int { /* ... */ }
int kept = KeepIf(numbers, (n) => n % 2 == 0);

Iterator pipelines are a separate surface and do not take inline lambdas. They use payload syntax instead: numbers->Filter(|n| => n % 2 == 0). See the Iterators chapter.

Closures#

A closure is a function that “closes over” and captures variables from its surrounding scope. When a lambda references a local variable from the function where it was created, it becomes a closure.

fn CreateGreeter(string greeting) : fn<(string) : string> {
    // This lambda captures the 'greeting' variable.
    return (name) => "$greeting, $name!";
}

var helloGreeter = CreateGreeter("Hello");
string message = helloGreeter("Wax"); // Returns "Hello, Wax!"

Working with Named Functions#

Any named function, including instance methods, can be assigned to a variable of a matching function type. When an instance method is assigned, it automatically creates a closure that captures the this instance.

class Calculator {
    private int factor;
    constructor(int factor) { this.factor = factor; }
    fn Multiply(int value) : int { return value * this.factor; }
}

var calc5 = new Calculator(5);
// This creates a closure that captures the 'calc5' instance.
fn<(int) : int> multiplyBy5 = calc5.Multiply;
int result = multiplyBy5(3); // returns 15

Advanced Function Topics#

Trailing Closures#

If the last parameter of a function is a function type, you can provide that argument after the function call’s parentheses using a block. This creates a syntax that looks like a custom control flow block and is the idiomatic way to handle resource management.

// A function that takes a simple action with no parameters.
fn OnButtonClick(fn<() : void> action) { /* ... */ }

// The | | is not required if the closure has no parameters.
OnButtonClick() {
    Log("Button was clicked!");
};

Payload Parameters#

If the closure accepts parameters, you must declare them in a payload block |...| before the main body {...}. The parameters listed in the payload block map directly to the parameters of the function type, in the same order.

• You can omit parameters you don’t need, starting from the end.
• You can use an underscore _ to explicitly ignore a parameter in any position.
• If you don’t need to access any parameters, or if the closure takes no parameters, the entire |...| block can be omitted.

fn ForEach<T>(T[] items, fn<(T, int) : void> action) { /* ... */ }
string[] names = [] { "Alice", "Bob", };

// Using all parameters
ForEach(names) |name, index| {
    Debug.Log("${index}: ${name}");
};

// Omitting the last parameter (index)
ForEach(names) |name| {
    Debug.Log(name);
};

// Ignoring the first parameter (name)
ForEach(names) |_, index| {
    Debug.Log("Processing item at index ${index}");
};

// Ignoring all parameters, the |...| block is omitted entirely.
ForEach(names) {
    Log("Processed an item.");
};

Lambda Modifiers#

Lambdas can be marked with special modifiers to control their behavior.

static: Guarantees the lambda does not capture any variables, preventing a closure allocation.

state: A lambda becomes stateful by containing state declarations.

Error Handling#

When a function type can throw an error, the throws declaration is part of its type. The try keyword must be used where the function is invoked, not where it is defined.

// This function takes a callback that might throw.
fn ExecuteIfValid(string data, fn<() : void throws ValidationError> action) {
    if (data.length > 0) {
        // The error propagates from this invocation point.
        action();
    }
}

fn Process() throws ValidationError {
    // The 'try' is required here at the call-site.
    try ExecuteIfValid("someData", () => {
        throw new ValidationError("Failed!");
    });
}

Arrays and Collections in Wax#

Wax provides a rich set of collection types for storing and manipulating groups of data. These range from high-level, dynamic collections to low-level, performance-oriented arrays and memory views.

This document provides an overview of the primary collection types. For more advanced topics, see the detailed documentation on Iterators, Array Initializer Lists, and Memory and Spans.

Standard Collection Types#

These are the most common, general-purpose collections for everyday use.

Single-Dimensional Arrays: T[]#

This is the primary array type in Wax. It is a reference type that points to a contiguous, fixed-size block of memory on the heap.

• Behavior: Reference semantics (the reference is copied on assignment, not the data).
• Allocation: Heap-allocated and managed by the garbage collector.
• Properties: .size provides the number of elements in the array.
• Use Case: The default choice for storing a known number of elements.

// Create a heap-allocated array of 3 integers.
var scores = new int[3];
scores[0] = 95;
scores[1] = 87;
scores[2] = 100;

new T[n] requires a valid zero. It zero-fills its n slots, so it is legal only when zero is a real value of T: primitives, enums with a valid zero, nullable T? (whose zero is null), and blittable structs. For a non-null reference element (string, a class, another T[]), zero would be a null hole, so new T[n] is a compile error; build a dense array with an initializer list, the generator form new T[n] |i| { yield … }, or a lateinit T[] you fill and promote (see Late-Initialized Arrays below). new T[0] is always legal (it fills nothing).

Allocation-size arithmetic is exact. For a heap allocation new T[n], Wax replays the local +, -, and * computation that produced n in signed 64-bit arithmetic immediately before allocation. If that computation overflows int64, or its final value is outside int32, allocation panics with integer_overflow at the new statement. Parameters, loads, casts, and call results are the already-observed values, so they are never evaluated again. This applies to lateinit and jagged heap allocations too; ordinary integer arithmetic and stack allocations keep their normal wrapping behavior.

Jagged Arrays (T[][])#

A jagged array is an array of arrays, where each inner array can have a different size. Under the hood, int[][] is Array<Array<int>?>, so the inner element type is implicitly nullable and inner arrays can be null.

Pre-allocated Jagged Arrays#

When all inner arrays have the same size, you can specify all dimensions at once. Sizes are provided left-to-right; you can stop at any point but cannot skip dimensions.

// All inner arrays pre-allocated with size 5.
var grid = new int[3][5];
grid[0][2] = 42; // inner arrays are pre-allocated, so indexing works immediately

// Three-level jagged, fully pre-allocated.
var cube = new int[2][3][4];

// Partial pre-allocation: only outer array allocated, inner arrays are null.
var ragged = new int[3][];

// Partial: outer and middle allocated, innermost null.
var partial = new int[2][3][];

Manual Inner Allocation#

When inner arrays have different sizes, allocate the outer array first, then assign each inner array individually.

var grid = new int[3][];
grid[0] = new int[2]; // 2 columns in the first row
grid[1] = new int[4]; // 4 columns in the second row
grid[2] = new int[3]; // 3 columns in the third row

// Accessing elements uses sequential brackets.
grid[0][1] = 10;

List<T>#

The List<T> is the primary general-purpose, resizable collection. It automatically manages an internal array, growing its capacity as needed when new elements are added.

• Properties: .size (the number of elements in the list) and .capacity (the size of the internal storage).
• Common Operations: Adding (.Add), removing (.Remove, .RemoveAt), and clearing (.Clear) elements.

import List from Wax;

var names = new List<string>();
names.Add("Alice");
names.Add("Bob");
Log("Size: ${names.size}"); // Outputs: Size: 2

Dictionary<K, V>#

A Dictionary<K, V> stores a collection of key-value pairs, providing fast lookups based on the key.

• Properties: .size (the number of key-value pairs).
• Common Operations: Checking for a key (.Has), exact lookup (.TryGetValue), ergonomic nullable lookup (.GetValue), and removing a key-value pair (.Remove).

import Dictionary from Wax;

var playerScores = new Dictionary<string, int>();

// Add or update items using index assignment.
playerScores["Alice"] = 100;
playerScores["Bob"] = 95;

// Retrieve an item. The indexer throws on missing keys, so this needs try.
// A bare `try` propagates, so the enclosing function must declare `throws`;
// otherwise attach a catch, as in the indexer examples below.
int aliceScore = try playerScores["Alice"];

// Safe access with TryGetValue.
int? score;
if (playerScores.TryGetValue("Alice", out score)) {
    Log("Alice's score: ${score!}");
}

// The out value is nullable because V may not have a default value. The bool
// distinguishes a missing key from a present key whose stored value is null.

// When missing and a stored null are equivalent, GetValue supports payload syntax.
if (playerScores.GetValue("Bob")) |bobScore| {
    Log("Bob's score: ${bobScore}");
}

Set<T>#

A Set<T> stores a collection of unique elements. It provides high-performance set operations. T must satisfy the Hashable constraint.

• Properties: .size (the number of unique elements).
• Common Operations: Adding (.Add), removing (.Remove), and checking for containment (.Has).

import Set from Wax;

var tags = new Set<string>();
tags.Add("ui");
tags.Add("player");
tags.Add("ui"); // This is a duplicate and will be ignored.

Log(tags.size); // Outputs: 2
bool hasPlayerTag = tags.Has("player"); // true

Stack<T> and Queue<T>#

For more specific access patterns, Wax provides Stack<T> and Queue<T>.

• Stack<T>: A last-in, first-out (LIFO) collection for pushing and popping elements.
• Queue<T>: A first-in, first-out (FIFO) collection for enqueuing and dequeuing elements.

Indexers#

Indexers allow types to support [] bracket access syntax, just like arrays. They are declared using get this(...) and set this(...), following the same pattern as property getters and setters.

Using Indexers#

The built-in collection types support bracket access through indexers:

import List from Wax;
import Dictionary from Wax;
import Span from Wax;

// List<T> supports integer indexing
var list = new List<int32>();
list.Add(10);
list.Add(20);
int32 first = list[0];   // read via indexer getter
list[1] = 99;            // write via indexer setter

// Dictionary<K, V> supports key-based indexing
var scores = new Dictionary<string, int32>();
scores["Alice"] = 100;   // write via indexer setter

// The Dictionary getter throws on missing keys, so this needs try
int32 s = try scores["Alice"] catch |e| { yield 0; };

// Span<T> supports integer indexing
Span<int32> span = list.ToSpan();
int32 val = span[0];
span[0] = 42;

Declaring Indexers#

Indexers are declared with get this and set this using the same syntax as properties. The getter’s parameters define the index signature, and its return type defines the element type. The setter takes the same index parameters plus a trailing value parameter.

class Grid {
    private int32[] data;
    private int32 width;

    constructor(int32 w, int32 h) {
        width = w;
        data = new int32[w * h];
    }

    public get this(int32 x, int32 y) : int32 {
        return data[y * width + x];
    }

    public set this(int32 x, int32 y, int32 value) {
        data[y * width + x] = value;
    }
}

var grid = new Grid(10, 10);
grid[3, 4] = 42;
int32 cell = grid[3, 4];

Indexers can have any number of parameters and any parameter types. The getter and setter must agree on parameter types, and the getter’s return type must match the setter’s value (last) parameter type.

Throwing Indexers#

Unlike regular properties, indexers can declare throws. This is used by Dictionary<K, V> whose getter throws ItemNotFoundError when a key is missing:

// Getter that throws
public get this(K key) : V throws ItemNotFoundError;

// Setter (does not throw, because setting always succeeds)
public set this(K key, V value);

Callers must use try when reading from a throwing indexer:

// Propagate the error
int32 val = try dict["key"];

// Handle with catch
int32 val = try dict["key"] catch |e| { yield 0; };

// Throwing setters use statement-level try
try map[0] = 42;

Indexers in Interfaces and Constraints#

Indexers can be declared in interfaces and constraints, allowing generic code to work with any indexable type:

interface IReadable {
    get this(int32 index) : int32;
}

constraint Indexable {
    get this(int32 index) : int32;
}

fn Sum<T>(T source, int32 count) : int32 where T is Indexable {
    int32 total = 0;
    int32 i = 0;
    while (i < count) {
        total = total + source[i];
        i = i + 1;
    }
    return total;
}

Virtual and Abstract Indexers#

Indexers support virtual, abstract, and override, following the same rules as methods and properties:

abstract class Base {
    public abstract get this(int32 index) : int32;
    public abstract set this(int32 index, int32 value);
}

class Derived extends Base {
    private int32[] data;

    public override get this(int32 index) : int32 {
        return data[index];
    }

    public override set this(int32 index, int32 value) {
        data[index] = value;
    }
}

Within a derived class, base[index] calls the base class indexer, and this[index] calls the current class indexer.

Restrictions#

• A type can have at most one indexer.
• Indexer parameters cannot be out or ref.
• Compound assignment (list[i] += 1) is not supported on indexers.

Collection Iteration#

Iteration with foreach#

The standard way to iterate over a collection is with a foreach loop. It uses the payload syntax |...| to declare the loop variable.

foreach (names) |name| {
    Log("Hello, ${name}!");
}

For transforming collections, Wax provides a zero-cost Iterator system using the -> operator.

// Get the scores of all players with names longer than 3 characters.
var highScores = playerScores
    ->Filter(|kvp| kvp.key.length > 3)
    ->Map(|kvp| kvp.value)
    ->ToList();

A Note on Collection Interfaces#

Wax provides collection interfaces (e.g., IList<T>, IStack<T>). However, their use in API signatures is generally discouraged. For performance reasons, it is almost always better to use constraints to write generic functions that operate on collections. This allows the compiler to generate specialized code and avoid the runtime overhead of virtual method calls that come with interfaces.

Advanced Collection Types#

These types serve specific needs and are not intended for general-purpose programming.

Memory Views with Spans#

For high-performance scenarios, Wax provides Span<T>, a safe mutable view into a contiguous region of memory owned by another collection (like a T[] or List<T>). A span is a scoped struct containing a backing address and an element count. It borrows rather than owns or retains the backing storage, so it cannot be stored where it could outlive that storage. Collections that own contiguous memory provide methods to create spans from their data.

Mutating through a span marks the owner dirty so the runtime’s frame-end diff sees the change, and panics if the owner is currently pinned by an iterator.

A span composes with ? like any other type: Span<T>? is a stack value that holds the span inline beside a presence flag, so a present-but-empty view is distinct from an absent one. What stays illegal is putting a span into heap storage: Span<T>[], Span<T>?[], and a span field in a non-scoped struct are all rejected, with or without the ?.

For a complete guide, see the Memory and Spans documentation.

var numbers = new int[] { 10, 20, 30, 40, 50, };

// Create a span that views the entire array.
scoped Span<int> fullSlice = numbers.ToSpan();

// Create a span that views a portion of the array.
scoped Span<int> middleSlice = numbers.Slice(1, 3); // Views { 20, 30, 40 }

middleSlice[0] = 99; // This modifies the original 'numbers' array.
// 'numbers' is now { 10, 99, 30, 40, 50 }

Late-Initialized Arrays: lateinit T[]#

Because new T[n] is rejected for a non-null reference element (it would leave null holes), Wax provides lateinit T[]: a checked array that starts with every slot unassigned and is filled slot-by-slot. It is the sanctioned way to build a non-null-element array incrementally without a nullable stand-in.

• The monotone law: a slot is never un-assigned once written, so a proof that a region is hole-free stays valid for the array’s lifetime.
• Prefix modifier: lateinit is valid only on an array type, and binds the outermost level. It cannot combine with stackalloc, and an initializer list or generator (which fill every slot, yielding a dense array) contradict it.
• Single dimension only: new lateinit T[n] cannot be jagged. A jagged construction is refused by name, so lateinit T[] is the only shape you can actually build.
• Construction: new lateinit T[n] mints n unassigned slots. It is the one allocation form exempt from the valid-zero gate above.

Every read is guarded: touching an unassigned slot panics. The per-slot surface needs no proof:

lateinit string[] names = new lateinit string[3];  // 3 unassigned slots
names[0] = "ann";                       // checked write
bool has0 = names.IsAssigned(0);        // per-slot test (never panics) -> true
bool all  = names.AllAssigned;          // whole-array test -> false (1 of 3 set)
names.Fill("?");                        // writes every slot AND records hole-freeness

Viewing the buffer as contiguous values first proves the viewed region is hole-free (a non-null read must never observe a hole):

string[] dense       = names.AsArray();          // verify [0,size) -> re-view SAME buffer as dense T[] (no copy)
Span<string> window  = names.Slice(0, 2);        // verify just [0,2) -> readable Span<T>
WriteOnlySpan<string> w = names.ToWriteOnlySpan(); // write-only view; needs no proof, records none

AsArray proves the whole array and Slice proves only its window (an array with holes elsewhere can still be sliced over a dense region); both panic on the first hole they find. The hole-observing read algorithms (Sort, Contains, foreach-over-values, …) do not live on lateinit T[]. Promote via AsArray() and use the dense T[] surface.

Conversions: a dense T[] widens implicitly to lateinit T[]; the reverse requires AsArray(). The boolean membership test late is T[] consults the runtime hole-freeness bit, so it is true exactly when the array has been proven dense; it does not promote or retype the value. Array as casts are rejected; use AsArray() for the checked promotion. The widening test dense is lateinit T[] is statically always true and reads no bit. lateinit arrays cannot cross the host boundary, so host-facing arrays are dense T[] or T?[].

The Wax Type System#

The Wax type system is built on two fundamental concepts: value types and reference types. The difference decides how your data is stored, copied, and compared.

• Value Types: These types are stored directly, either on the execution stack or inline within a containing object. When you assign a value type or pass it to a function, you are creating a complete copy of the data. They are ideal for small, self-contained data structures.
  • Stored on stack or inline.
  • Copied by value on assignment.
  • Cannot inherit from classes or implement interfaces.
  • Every assignment, argument, and return copies the whole value, so size is a performance concern rather than a hard limit.
• Reference Types: These types are stored on the memory heap, and your code interacts with them through a reference (or pointer). When you assign a reference type or pass it to a function, you are only copying the reference, not the underlying object. Both variables then point to the same object in memory.
  • Stored on the heap and accessed through pointers.
  • Passed by pointer (reference is copied).
  • Support inheritance and polymorphism.
  • Can implement interfaces.

A Note on Boxing: Some languages can implicitly wrap a value type in a reference type, a process called “boxing” which can cause hidden performance costs. Wax does not support boxing, ensuring that the performance characteristics of your types are always explicit and predictable.

Reference Identity#

Use object.ReferenceEquals(left, right) to compare whether two reference values point at the same heap object. It accepts reference types and nullable reference types, including string and string?, through implicit conversion to object?. It does not accept value types or nullable value types because Wax does not box values.

ReferenceEquals compares identity, not contents. For example, string == string uses string value equality, while object.ReferenceEquals(stringA, stringB) only returns true when both variables refer to the same string object. Two null nullable reference values compare as the same reference.

Composite Type Members#

Both structs and classes are composite types, meaning they group data and behavior together using members. The primary members are fields, properties, methods, and constructors.

Fields#

Fields are variables that store data directly within an instance of the type.

struct Point {
    float x; // field
    float y; // field
}

Methods#

Methods are functions that define the behavior of a type and can operate on its data.

struct Point {
    float x;
    float y;

    fn Distance(Point other) : float { /*...*/ } // method
}

Constructors#

Constructors are special methods responsible for creating and initializing a new instance of a type.

struct Point {
    float x;
    float y;
    
    constructor(float x, float y) { /*...*/ } // constructor
}

Compact Field Headers#

A struct or a class whose shape is its fields can declare them in the header, directly after the type name:

struct Point(float x, float y);
class User(string name, int32 id = 0);
struct Pair<T>(T first, T second) where T is struct;

Each entry declares one public, writable instance field, in header order, and the header as a whole declares the type’s single unnamed constructor, which assigns every entry to its field. struct Point(float x, float y); means exactly:

struct Point {
    public float x;
    public float y;

    public constructor(float x, float y) {
        this.x = x;
        this.y = y;
    }
}

The generated members are ordinary members: header order is field-layout order and positional-argument order, entry names are the field names and the named-argument names, and an entry’s default is an ordinary constructor default rather than a field initializer.

A body may follow the header instead of the ;, and carries whatever members the type needs:

struct Vec(float x, float y) {
    fn LengthSquared() : float { return x * x + y * y; }
}

Members written in the body meet the generated ones under the ordinary duplicate rules, so a body field or a second unnamed constructor that collides with the header is an error. ref, out, and scoped are refused on an entry: it is stored, not borrowed.

A compact class may implement an interface, satisfying it through its members like any other class, and may extend a base:

class Player(string name, int32 points) implements IHasScore {
    public get Score() : int32 { return points; }
}

class Enemy(int32 health) extends Actor;

The generated constructor takes the implicit : base() that any constructor written without a base call takes, so the base must have a parameterless constructor. A base whose constructor requires arguments is the ordinary missing-base-call error: there is nowhere in a header to spell : base(...), so write that constructor out in full.

is is refused alongside a header — a constraint declaration carries neither fields nor a constructor.

Properties#

Properties provide controlled access to a type’s data through get and set accessors. They look like methods when declared, but are used like fields, without parentheses.

class Character {
    private int _health;

    // 'Health' is a property that controls access to the private '_health' field.
    public get Health() : int {
        return this._health;
    }
    public set Health(int value) {
        // The setter can contain logic, like validation.
        this._health = value < 0 ? 0 : value;
    }
}

// --- Usage Example ---
var hero = new Character();

// The 'set' accessor is called using a simple assignment.
hero.Health = 90;

// The 'get' accessor is called by accessing the value.
int currentHealth = hero.Health; // currentHealth is now 90

// The setter's validation logic is automatically used.
hero.Health = -10;
int newHealth = hero.Health; // newHealth is now 0, not -10.

Member Modifiers#

Member declarations can be prefixed with keywords that modify their behavior and visibility.

Visibility Modifiers#

These keywords control where a member can be accessed from.

• public (Default): The member can be accessed from anywhere.
• protected: The member can only be accessed by the containing class and its derived classes.
• internal: The member can only be accessed from the same module.
• private: The member can only be accessed by the containing type.

class Example {
    public int a;    // Accessible everywhere
    private int b;   // Accessible only within Example
    protected int c; // Accessible within Example and its subclasses
    internal int d;  // Accessible within the same module
}

The static Modifier#

A static member belongs to the type itself, not to any specific instance. You access it through the type name.

• Static Fields: A variable shared by all instances of the type.
• Static Properties: A property that is not tied to a specific instance’s state.
• Static Methods: A function that does not operate on an instance (this is not available).

class Game {
    // A static field to track the total number of players across all games.
    public static int totalPlayers = 0;

    // A static property to get the name of the game engine.
    static get EngineName() : string {
        return "WaxEngine";
    }

    // A static method to provide help text.
    static fn GetHelpText() : string {
        return "This is a generic help message for all games.";
    }
}

// Accessing static members
int players = Game.totalPlayers;
string engine = Game.EngineName;
string help = Game.GetHelpText();

Immutability with readonly#

The readonly keyword enforces immutability, preventing data from being changed after initialization.

Readonly Fields#

A readonly field can only be assigned a value at its declaration or within a constructor of the same type.

class UserProfile {
    readonly int userId; // This field is immutable.
    string displayName;

    constructor(int id, string name) {
        this.userId = id; // VALID: Assignment in a constructor.
        this.displayName = name;
    }

    fn ChangeId(int newId) {
        // this.userId = newId; // ERROR: Cannot assign to a readonly field.
    }
}

Structs: Composite Value Types#

structs are the way you define custom composite value types in Wax. Along with enums (which define a set of named constants), they are one of the two kinds of user-defined value types. They are lightweight, efficient, and ideal for representing simple data structures.

// This struct groups two floating-point numbers into a single logical unit,
// using fields, a constructor, and a method.
struct Point {
    float x;
    float y;
    
    constructor(float x, float y) {
        this.x = x;
        this.y = y;
    }
    
    fn Distance(Point other) : float {
        float dx = this.x - other.x;
        float dy = this.y - other.y;
        return Math.Sqrt(dx * dx + dy * dy);
    }
}

Classes: The Primary Reference Type#

Classes are used for more complex objects, especially those that need to manage state or participate in inheritance hierarchies. They are the foundation of Object-Oriented Programming in Wax.

// A base class that defines the core features of an Animal.
class Animal {
    string name;
    
    constructor(string name) {
        this.name = name;
    }
    
    // A 'virtual' method can be replaced by derived classes.
    virtual fn MakeSound() : string {
        return "Some generic animal sound";
    }
}

Choosing Between Structs and Classes#

The most important difference is how they behave when assigned.

• Structs (Value Types) are copied.
• Classes (Reference Types) share the same instance.

// Structs are copied on assignment.
var p1 = new Point(10, 20);
var p2 = p1; // p2 is a complete copy of p1.
p2.x = 30;   // This only changes p2. p1.x is still 10.

// Classes share the same instance.
var animal1 = new Animal("Fido");
var animal2 = animal1; // animal2 refers to the *same object* as animal1.
animal2.name = "Max";  // This changes the name for both animal1 and animal2.
                       // animal1.name is now "Max".

sizeof(T)#

The sizeof expression returns the size in bytes of a type as a compile-time constant int32. It can be used anywhere an expression is expected, including in const declarations.

const int32 kIntSize = sizeof(int32);     // 4
const int32 kDoubleSize = sizeof(double); // 8

struct Vec3 { float x; float y; float z; }
const int32 kVec3Size = sizeof(Vec3);     // 12

For value types (primitives, enums, structs), sizeof returns the laid-out size including alignment padding. For classes and other reference types, sizeof returns the full heap object size (including the 8-byte type header).

sizeof can be used with generic type parameters. In this case, the size is resolved after generic instantiation:

fn GetSize<T>(T value) : int32 {
    return sizeof(T);
}

Using sizeof on a recursive struct (a struct that contains itself as a field) produces a compile-time error.

Enumerations#

Enumerations (or enums) are a value type defining a set of named constants. They are ideal for representing concepts that have a limited number of distinct states, such as a status, a category, or a set of options.

Wax provides two kinds of enumerations: normal enums for distinct values, and flags for values that can be combined as bitwise flags.

Normal Enumerations#

A normal enum defines a set of unique named values. By default, the underlying type of an enum is int, and the values are automatically assigned, starting from 0 and incrementing by one.

// A simple enum for tracking game states.
enum GameState {
    case MainMenu;  // 0
    case Playing;   // 1
    case Paused;    // 2
    case GameOver;  // 3
}

// Using the enum
GameState currentState = GameState.Playing;
if (currentState == GameState.Playing) {
    // ...
}

Backing Types and Explicit Values#

You can specify a different integral type for an enum (like byte, short, or uint) and assign explicit values to its members. If you assign an explicit value, subsequent members will auto-increment from that point.

// An enum with an explicit backing type and values.
enum StatusCode extends short {
    case Success = 200;
    case NotFound = 404;
    case ServerError = 500;
}

// An enum with mixed explicit and auto-incrementing values.
enum Priority extends byte {
    case Low;          // 0
    case Medium = 5;   // 5
    case High;         // 6 (increments from Medium)
    case Critical = 10; // 10
}

Flags#

A flags type is designed for bitwise operations, so multiple values can be combined into a single instance. It is declared with the flags keyword, which is a standalone type declaration rather than a modifier on enum.

• Flags must have an unsigned integral backing type (e.g., uint, ushort, byte). The default is uint.
• If you don’t assign a value, the compiler automatically assigns the smallest unused power of two (1, 2, 4, 8, …).
• You can create composite members by combining other members with the bitwise OR | operator.

flags Permissions extends uint {
    case Read;         // 1 (auto-assigned)
    case Write;        // 2 (auto-assigned)
    case Execute;      // 4 (auto-assigned)
    case Delete = 8;   // 8 (explicitly assigned)

    // Composite members are useful shortcuts.
    case ReadWrite = Read | Write; // 3
    case All = Read | Write | Execute | Delete; // 15
}

Flag Decomposition Rule#

A key safety feature of flags is that the compiler validates them at compile time. Any member with a multi-bit value (like ReadWrite = 3) must be composed entirely of bits that correspond to other single-bit members defined in the same flags type.

flags Example extends uint {
    case A = 1;        // Single bit (power of 2)
    case B = 2;        // Single bit
    case C = 4;        // Single bit
    case AB = 3;       // VALID: Decomposes to A | B
    case AC = 5;       // VALID: Decomposes to A | C
    case BC = 6;       // VALID: Decomposes to B | C
    case ABC = 7;      // VALID: Decomposes to A | B | C

    // ERROR: This is invalid because the value 15 contains the bit for '8',
    // but there is no single-bit member defined with the value 8.
    // case Invalid = 15
}

This rule also applies when casting from an integer to a flags type.

Using Flags#

You can manipulate flags using bitwise operators (|, &, ^) to add, check for, or toggle values.

// Start with Read and Write permissions.
Permissions userPerms = Permissions.Read | Permissions.Write;

// Add Execute permission.
userPerms |= Permissions.Execute;

// Check if a specific permission exists.
if ((userPerms & Permissions.Read) != 0) {
    // User has read permission.
}

// Remove Write permission.
userPerms &= ~Permissions.Write;

Flag Helper Methods#

For convenience, Wax automatically provides helper methods on all flags types:

• HasValue(mask): Returns true if any of the bits in the given mask are set.
• HasAll(mask): Returns true if all of the bits in the given mask are set.
• Add(mask): Returns a new value with the given flags added.
• Remove(mask): Returns a new value with the given flags removed.
• Toggle(mask): Returns a new value with the given flags flipped.

Permissions userPerms = Permissions.ReadWrite;

bool canRead = userPerms.HasValue(Permissions.Read); // true
bool canExecute = userPerms.HasValue(Permissions.Execute); // false

Permissions newPerms = userPerms.Add(Permissions.Execute); // now has Read, Write, Execute

Default Enum Case#

You can explicitly designate one member of an enum as its default value. This makes the enum type compatible with the default keyword.

To mark a case as the default, prefix it with the default keyword. Only one case can be marked as the default. If no member is marked, the enum type is not compatible with the default keyword, and using default(MyEnum) will result in a compile-time error. Both enum and flags behave the same way.

enum Color {
    default case Black; // This case is the default
    case Red;
    case Blue;
}

// Now you can use the default keyword with this enum.
Color c = default; // c is Color.Black

Enum Members#

Enums and flags can have methods and properties, but they cannot have fields or constructors. Behavior therefore lives on the type itself.

enum Color {
    case Red;
    case Green;
    case Blue;

    public get IsPrimary() : bool {
        return true; // All are primary in this model
    }

    public fn GetHexCode() : string {
        switch (this) {
            case Red: { return "#FF0000"; }
            case Green: { return "#00FF00"; }
            default: { return "#0000FF"; }
        }
    }
}

// Usage
string hex = Color.Green.GetHexCode(); // "#00FF00"

Type Conversion#

You must use an explicit cast to convert between an enum/flags and its underlying integral type.

• as!: Performs a forced cast. If the integral value does not correspond to a defined member (or cannot be decomposed for a flags type), the program will panic.
• as?: Performs a safe cast. If the cast fails, it returns null.

The check is a test of a numeric value against the declared cases, so the other side of the cast must be a value the check can run on: a numeric type, or another enum. Casting an enum to or from a string, a json, or a reference type is a compile error. Convert through the backing integer instead. Both sides must also be non-nullable; unwrap first.

Color color = Color.Blue;
int value = color as! int; // 2

StatusCode status = 200 as! StatusCode; // StatusCode.Success

// Panicking cast
// StatusCode invalid = 999 as! StatusCode; // PANIC! 999 is not a valid value.

// Safe cast
StatusCode? maybeStatus = 999 as? StatusCode; // null
if (maybeStatus) {
    // ...
}

Object-Oriented Programming#

Inheritance#

Inheritance allows a new class (the derived class) to be based on an existing class (the base class). The derived class inherits the members of the base class and can add new members or modify the inherited behavior.

A core principle in Wax is that all member names (fields, properties, and methods) must be unique within an entire type hierarchy. This eliminates ambiguity and makes method resolution simple and predictable. The only exception is when explicitly overriding a virtual or abstract member. Constructors are also exempt from this rule.

virtual, override, and sealed#

These keywords manage how methods and properties can be modified in a derived class.

• virtual: Marks a method or property in a base class, allowing it to be replaced by a derived class.
• override: Provides a new implementation for a virtual member from the base class.
• sealed: Placed on a class, it prevents any other class from extending it. Placed on an override member, it ends that member’s override chain: the member still dispatches virtually, but no further derived class may override it again. sealed is only valid together with override: a member that overrides nothing is already un-overridable unless it is virtual.

class Dog extends Animal {
    // Subclasses of Dog inherit this, but cannot replace it.
    public sealed override fn MakeSound() : string {
        return "Woof";
    }
}

class Puppy extends Dog {
    // ERROR: Dog.MakeSound is sealed.
    // public override fn MakeSound() : string { return "Yip"; }
}

// --- Example with Methods ---
class Animal {
    // This method can be replaced by subclasses.
    public virtual fn MakeSound() : string {
        return "Some generic animal sound";
    }
}

class Dog extends Animal {
    // This provides a specific version of the method for Dogs.
    public override fn MakeSound() : string {
        return "Woof!";
    }
}

// --- Example with Properties ---
class BaseValue {
    // Base class provides a read-only virtual property.
    public virtual get Value() : int { return 0; }
}

class SettableValue extends BaseValue {
    private int storedValue;

    // Override the getter.
    public override get Value() : int {
        return this.storedValue;
    }

    // Add a setter, making the property read-write in the derived class.
    public set Value(int value) {
        this.storedValue = value;
    }
}

abstract Classes and Members#

An abstract class is a special kind of base class that cannot be instantiated on its own. It serves as a template that other classes must build upon.

An abstract member (method or property) has no implementation and must be overridden in any concrete (non-abstract) derived class.

// 'Shape' cannot be instantiated directly.
abstract class Shape {
    // An abstract method that derived classes MUST implement.
    public abstract fn GetArea() : float;

    // A regular virtual method that can optionally be overridden.
    public virtual fn GetName() : string {
        return "A generic shape";
    }
}

class Circle extends Shape {
    public float radius;

    // We MUST provide an implementation for the abstract GetArea method.
    public override fn GetArea() : float {
        return 3.14f * this.radius * this.radius;
    }
}

// var s = new Shape(); // ERROR: Cannot create an instance of an abstract class.
var c = new Circle();
c.radius = 10.0f;
float area = c.GetArea(); // 314.0f

Constructors in Inheritance#

Constructors have special rules to ensure that both base and derived classes are initialized correctly.

Default Constructors#

If you do not declare any constructors in a class, the compiler may provide a public, parameterless default constructor automatically. However, this only happens if it is safe to do so. A default constructor will not be generated if:

1. Any other constructor is explicitly declared.

   class Example {
       // The presence of this constructor prevents the default one.
       constructor(int value) { }
   }
   // var ex = new Example(); // ERROR: No parameterless constructor exists.
   

2. The base class does not have an accessible parameterless constructor.

   class Base {
       constructor(int value) { } // No parameterless constructor.
   }
   class Derived extends Base {
       // ERROR: No default constructor is generated because it cannot
       // implicitly call a non-existent base() constructor.
   }
   

3. The class has uninitialized non-nullable reference type fields. Value types (like int) and nullable reference types (like string?) have safe default values (0, false, null). A non-nullable reference type does not, so an empty constructor would violate Wax’s definite assignment rule.

   class User {
       string name; // ERROR: Non-nullable reference type is not initialized.
       
       int score;          // OK: Value types default to 0.
       string? avatarUrl;  // OK: Nullable types default to null.
   
       // A default constructor cannot be generated because
       // it would not initialize the 'name' field.
   }
   

Explicit Constructor Chaining#

A constructor in a derived class is required to call a constructor from its base class. If you do not specify one, the compiler implicitly tries to call base().

• Use : base(...) to explicitly call a constructor on the base class.
• Use : this(...) to call another constructor in the same class (which must eventually chain to a base constructor).

class Base {
    public int value;
    constructor(int value) {
        this.value = value;
    }
}

class Derived extends Base {
    public string name;

    // This constructor explicitly calls the base constructor.
    constructor(int val, string name) : base(val) {
        this.name = name;
    }

    // This constructor chains to another constructor in THIS class.
    constructor(string name) : this(0, name) {
        // The call to :this(0, name) handles the base initialization.
    }
}

Named Constructors#

Because Wax does not support method overloading, you can create multiple constructors by giving them unique names. These can also be used in constructor chaining.

class Base {
    constructor() { /*...*/ }
    constructor FromValue(int value) { /* ... */ }
}

class Derived extends Base {
    // Calls the NAMED constructor in the base class.
    constructor(string name) : base.FromValue(name.length) {
        // ...
    }
}

Object Initializers#

A new expression can set members directly with a brace list, using .member = value. Keys may name fields or properties; a property key runs its setter.

class Point {
    public int x;
    public int y;
}

Point p = new Point { .x = 1, .y = 2 };

When the type is already known from context, it may be left off entirely. The keys drop their leading dot in this form:

Point p = new { x = 1, y = 2 };          // target: the declared local type

The type comes from whatever the expression is being assigned or passed to: a declared variable, a parameter, a return type, or the field or property on the left of an assignment.

fn Apply(Config c) : int { /* ... */ }

fn Make() : Point {
    return new { x = 5, y = 6 };         // target: the return type
}

Apply(new { width = 3, height = 4 });    // target: the parameter type
o.inner = new { v = 9 };                 // target: the field type

A nullable target constructs its underlying type, so Point? p = new { x = 1, y = 2 }; builds a Point and wraps it, so the result is never null.

If nothing supplies a type, the form is an error. var declares no type of its own, so var p = new { x = 1 }; is rejected. Write new Point { .x = 1 } there instead.

In both spellings a key must name a field or a property with a setter. A key that resolves to anything else, such as a method, a const, or a nested type, is rejected rather than ignored.

The brace list runs after the constructor, so each entry is an ordinary write and obeys the same rules as x.f = v. A readonly field is therefore not settable this way. Assign it in a constructor instead:

class Foo {
    public readonly int x;
    constructor(int v) { x = v; }
}

Foo a = new Foo(1);          // ok
Foo b = new Foo { .x = 1 };  // rejected: `x` is readonly

Construction Safety#

Wax’s null-safety guarantee requires that no code can observe a non-nullable field before it is assigned. Inside a constructor, the compiler enforces this with definite assignment (every field must be assigned on every path before the constructor exits) plus rules that keep the partially-constructed this from leaking into code that could read unassigned fields:

1. Overridable dispatch on this is rejected. Calling a virtual, override, or abstract member (including virtual property accessors) on this inside a constructor could land in a derived class’s override, which would see the derived class’s still-unassigned fields.

2. this cannot escape. Passing this as an argument, storing it, returning it from a helper, or capturing it as a value hands out a reference to an object whose derived fields are not yet assigned.

3. Non-virtual helpers compose. Calling a non-overridable method on this is allowed when the method is construction-clean: its body (transitively) performs no overridable dispatch on this and never leaks this. The compiler infers which fields the helper reads and assigns: a helper’s reads must already be assigned at the call site, and its assignments count toward the constructor’s definite-assignment obligation, so field-initializing helpers work naturally:

class Session {
    string token;

    constructor() {
        Init();  // OK: Init assigns 'token', satisfying definite assignment.
    }

    fn Init() {
        this.token = "fresh";
    }
}

4. base.Method() binds statically, so it is allowed when the base method is construction-clean; the base class’s own fields are already assigned because the base constructor runs first.

5. sealed classes (and structs) are exempt from rules 1 and 2 once all fields are assigned. A sealed type has no derived classes, so a fully-assigned this is a complete object, and it may call its virtual members and escape freely. This makes sealed the escape valve for registration patterns:

sealed class Node {
    int32 id;

    constructor(int32 id) {
        this.id = id;
        Registry.Track(this);  // OK: sealed + fully assigned.
    }
}

These rules apply to class, struct, and error constructors alike.

Member Access Control#

Fields, methods, properties, constants, and constructors carry a visibility modifier. public is the default when none is written.

• public: reachable from anywhere.
• internal: reachable from code in the same module.
• protected: reachable from the declaring type and its subclasses.
• private: reachable from the declaring type only.

private is type-private, not instance-private. Accessibility is decided by where the access is written, never by which object it is written against: any code lexically inside the declaring type’s body may reach a private member of that type on any instance: this, a parameter, a local, a field, or a value returned from a call.

class Account {
    private int32 balance;
    public constructor(int32 balance) { this.balance = balance; }

    private fn Rate() : int32 { return 3; }

    // A second instance of the same type is reachable, in every direction.
    fn Absorb(Account other) : int32 {
        balance = balance + other.balance;   // read another instance's private field
        other.balance = 0;                   // ...and write it
        return other.Rate();                 // ...and call its private method
    }
}

A lambda written inside a method body keeps that method’s access, so a nested closure reaches the same private members its enclosing method can.

Two rules bound this:

• private is not protected. A subclass cannot reach a private member of its base; only the declaring type itself can. Use protected to admit subclasses.
• Generic instantiations share one accessibility domain. A generic type is one declaration, so its body reaches private members of any instantiation of itself: code in Box<T> may touch a Box<int32>'s private field. Code in an unrelated type still cannot, whichever instantiation it names.

struct Box<T> {
    private int32 tag;
    public constructor() { this.tag = 0; }

    fn Peek(Box<int32> other) : int32 {
        return other.tag;                    // OK: same declaration, different instantiation
    }
}

class Outsider {
    fn Peek(Box<int32> b) : int32 {
        return b.tag;                        // ERROR: private to Box
    }
}

The visibility override (obj.private.member) is the deliberate escape hatch from these rules; see the modules and visibility section.

Interfaces#

An interface defines a contract: a set of public methods and properties that a type must implement. In Wax, only classes (reference types) can implement interfaces; structs (value types) cannot. This allows classes to participate in polymorphism by promising to provide a specific set of behaviors.

An interface itself cannot contain state (fields) or implementation details (constructors, method bodies).

// An interface defines a capability.
interface IDamageable {
    get Health() : int;
    fn TakeDamage(int amount);
}

// Classes can promise to provide that capability.
class Player implements IDamageable { /* ... */ }
class Barrel implements IDamageable { /* ... */ }

// struct Boulder implements IDamageable { /* ... */ } // ERROR: Structs cannot implement interfaces.

Using Interfaces as Types#

Interfaces earn their keep when used as types for fields, properties, and parameters. A field of type IDamageable can hold an instance of Player, Barrel, or any other class that implements the interface, so the code holding it never names a concrete type.

interface ILogger {
    fn Log(string message);
}

class ConsoleLogger implements ILogger {
    public fn Log(string message) { /* ... */ }
}

class FileLogger implements ILogger {
    public fn Log(string message) { /* ... */ }
}

// This class is decoupled from any specific logger implementation.
class App {
    private ILogger logger;

    constructor(ILogger logger) {
        this.logger = logger; // Store any object that can log.
    }

    fn DoWork() {
        this.logger.Log("Doing some work...");
    }
}

Interface Inheritance and Conflict Resolution#

Interfaces can inherit from other interfaces to compose larger contracts.

• Same Name, Same Signature: If multiple interfaces define a member with the exact same signature, a single implementation in a class will satisfy all of them.
• Same Name, Different Signature: If a class needs to implement two interfaces with conflicting members, or if an interface member conflicts with an existing member on the class itself, a public implementation is not possible. This is where explicit implementation is required.

Explicit Interface Implementation#

When a name conflict arises, or when you want to implement an interface member without making it a part of the class’s API, you can use explicit interface implementation.

An explicitly implemented member is not part of the class’s API and can only be accessed when the object is viewed through the lens of the interface (i.e., cast to the interface type).

// --- Scenario 1: Conflict between two interfaces ---
interface IWriter { fn Write(string data); }
interface IArchiver { fn Write(byte[] data); }

class DataHandler implements IWriter, IArchiver {
    public fn Write(string data) { /* ... */ }
    fn IArchiver.Write(byte[] data) { /* ... */ } // Explicit implementation
}

// --- Scenario 2: Conflict between a class and an interface ---
interface IAction {
    fn Execute();
}

class Task implements IAction {
    // This public method has a different signature and purpose.
    public fn Execute(bool force) {
        // ...
    }

    // Explicit implementation is required to satisfy IAction without a name collision.
    fn IAction.Execute() {
        this.Execute(false); // Can call the public method internally
    }
}

Explicitly implemented members can also be virtual and override, following the same inheritance rules as public members.

Type Casting#

Wax provides operators to safely work with types in an inheritance hierarchy.

Implicit Upcasting (Safe)#

You can implicitly convert an instance of a class to any of its base classes or to any interface it implements. This is called an upcast, and it is always safe because the derived class is guaranteed to contain all the members of its base types. The compiler can verify this relationship, so no explicit cast is needed.

class Task implements IAction { /* ... */ }
var myTask = new Task();

// Implicit upcast from Task to IAction. This is always safe.
IAction myAction = myTask; 

// Implicit upcast from Dog to its base class Animal.
Animal myPet = new Dog(); 

Explicit Downcasting with as (Potentially Unsafe)#

Converting from a base type or an interface back to a more specific derived type is called a downcast. This operation is not guaranteed to be safe at runtime, as the object might be a different derived type. Therefore, downcasts must always be explicit using the as! or as? operators.

• as?: Performs a safe cast. If the cast succeeds, it returns the re-typed object. If it fails, it returns null. This is the recommended way to perform a downcast.
• as!: Performs a forced cast. If the cast fails at runtime, the program will panic. Use this only when you are absolutely certain of an object’s type and a failed cast should be considered a critical, program-ending error.

fn ProcessAction(IAction action) {
    // The recommended way to downcast is 'as?' plus a payload capture, which
    // unwraps the result into a non-nullable binding.
    Task? maybeTask = action as? Task;
    if (maybeTask) |task| {
        // The cast succeeded, we can now use Task-specific members.
        task.Execute(true);
    } else {
        // The action was not a Task, handle accordingly.
    }
}

Generics#

Generics let you write one implementation that stays type-safe across many types. You can define classes, structs, interfaces, constraints, errors, and methods that work with any data type, deferring the choice of that type until the code is used.

The examples in this chapter assume these ordinary stdlib imports:

import Error from Wax;
import List from Wax;

The core problem generics solve is code duplication. Without them, you would need to write separate implementations of a class for each data type you want to support (e.g., IntList, StringList, etc.). Generics allow you to write a single List<T> and let the compiler handle the rest.

Generic Types and Methods#

You can create generic types and methods by adding a type parameter list, enclosed in angle brackets (<>), after the name. A type or method can have up to 32 type parameters.

In Wax, a type’s name is its unique identifier. You cannot define multiple types that share the same name but have a different number of generic parameters. For example, Thing, Thing<T>, and Thing<T, U> would be considered a name collision and must be given unique names.

// A generic class that acts as a simple container for any type.
public class Container<T> {
    private T? item;

    public fn Put(T item) {
        this.item = item;
    }

    public fn Take() : T? {
        var temp = this.item;
        this.item = null;
        return temp;
    }
}

// A generic utility method. The compiler can often infer the type.
class Utility {
    public static fn Swap<T>(ref T a, ref T b) {
        T temp = a;
        a = b;
        b = temp;
    }
}

Type Argument Inference#

A call that supplies no explicit type arguments infers them from its arguments. Every argument that is not a lambda is unified against its parameter type first. Then each lambda whose parameter types are fully determined by those bindings has its body checked with them, and the body’s type is unified against the delegate’s declared return type, binding whatever it still leaves open; this repeats until no lambda can be checked, so one lambda’s result may fix the parameter types of the next. A body of type X against a declared U? binds U = X; a body of type X? against a declared U binds U = X?; a bare null fixes nothing. Explicit type arguments always take precedence, and a type parameter that no argument fixes is reported by name.

class Lane<T> {
    fn Select<U>(fn<(T) : U> sel) : Lane<U> { ... }
}

Lane<int32> hp = robots.Select((r) => r.health);   // U inferred as int32 from the body

Referring to the Type Being Declared#

Inside a generic type’s own body, naming that type with its own parameters denotes the current instantiation, the same type this has. Box<T> written inside Box<T> is not a new or “open” type; it is this one. That holds for local declarations, return types, parameters, fields, type-test targets, new expressions, and nested generic arguments.

struct Box<T> {
    T value;
    public constructor(T value) { this.value = value; }

    fn Self() : Box<T> { return this; }        // return type

    fn Hold() : bool {
        Box<T> copy = this;                    // local declaration
        List<Box<T>> all = new List<Box<T>>(); // nested generic argument
        all.Add(copy);
        return all.size == 1;
    }
}

Naming a different argument is an ordinary instantiation and is constraint-checked as usual, so Box<U> inside Box<T> means Box of U and must satisfy Box’s constraints.

The Constraint System#

By default, a generic type parameter T is completely unknown. To make generics useful, you must apply constraints, which define the required “shape” (members, properties, etc.) and characteristics a type must have to be used as a type argument.

Declaring Constraints#

You can define a reusable set of requirements using the constraint keyword. This is useful for complex requirements that are used in multiple places.

// A constraint for types that have a unique identifier.
constraint Identifiable {
    fn GetId() : ulong;
}

Using Constraints: The where Clause#

Constraints are applied to generic parameters using a where clause, which appears after the return type (for methods) or after the type header (for types). The where clause uses the is keyword followed by a list of requirements combined with the & operator. The compiler ensures the list of requirements is valid and non-conflicting.

Angle brackets (<>) only introduce type parameter names. All constraints go in where.

A requirement can be one of the following:

• A base type (class or error type name).
• An interface name.
• A named constraint.
• A constraint qualifier (e.g., numeric, struct).
• A callable signature (callable<...>) for delegate-like invocation.

// A base class for game objects.
class GameObject { /* ... */ }

// An interface for things that can be saved.
interface ISaveable { fn Save(); }

// A named constraint for things that can be reset.
constraint Resettable { fn Reset(); }

// This function's type parameter 'T' has three requirements.
fn ProcessObject<T>(T obj) where T is GameObject & ISaveable & Resettable {
    // ...
}

// You can also use qualifiers directly as a requirement.
// This function will only accept floating-point types (float, double).
fn ProcessRealNumber<T>(T number) : void where T is real {
    // ...
}

Callable Constraints#

callable<...> is a contextual requirement that uses the same signature syntax as a function type, minus the leading fn. It proves that values of a generic type parameter can be invoked with normal call syntax inside the constrained scope.

fn Apply<T>(T f, int32 x) : int32
    where T is callable<(int32) : int32> {
    return f(x);
}

fn TryApply<T>(T f, ref int32 x, out string s) : bool throws Error
    where T is callable<(ref int32, out string) : bool throws Error> {
    return f(ref x, out s);
}

The current rule is exact delegate compatibility: a concrete fn<...> delegate type satisfies callable<...> only when the parameter count, parameter types, ref/out modes, return type, and throws type all match. Callable constraints do not imply construction, and new T() remains invalid unless another rule explicitly permits construction.

Constructor Constraints#

A named constraint can require a constructor with an exact name and parameter count. The unnamed constructor() form requires an accessible parameterless constructor. The constraint declaration’s parameter types are used to type-check calls made through the constraint:

constraint Constructable {
    constructor();
}

fn Create<T>() : T where T is Constructable {
    return new T();
}

class Widget {
    public constructor() { }
}

Widget widget = Create<Widget>();

The same rule applies to value types and primitives. For example, the standard library’s Wax-defined constructor makes int32 satisfy Constructable, so Create<int32>() is valid. A constructor constraint does not make default invoke a constructor; default remains the canonical zero-value expression.

Note: When a list of requirements becomes long or is used in multiple places, it’s good practice to combine them into a single, reusable named constraint. For example:

// verbose constraint list
fn ProcessObject<T>(T obj) where T is GameObject & ISaveable & Resettable { }

// is rewritable as a simple (and reusable) constraint list:

constraint ProcessableObject implements GameObject, ISaveable, Resettable {}

fn ProcessObject<T>(T obj) where T is ProcessableObject {
    // ...
}

This improves readability and makes the code easier to maintain.

Constraint Qualifiers#

Qualifiers are keywords that restrict the fundamental kind of a type. They can be used in two ways:

1. When declaring a named constraint, to limit what kinds of types can satisfy it.
2. Directly as a requirement for a generic parameter.

The numeric qualifiers form an implication lattice: signed and unsigned imply integral, and both integral and real imply numeric. A generic parameter constrained to one of the stronger qualifiers therefore also satisfies a weaker requirement, so a where T is signed function may forward T to a helper declared where U is integral, and a where T is real function may forward T to a helper declared where U is numeric. The implication is one-directional: numeric does not satisfy the narrower real or integral, integral does not satisfy either sign qualifier, and real does not satisfy integral.

Static If Type Predicates#

static if is a branch statement for open generic code. It selects a branch during generic specialization based on type predicates over generic parameters; it is not a general compile-time expression evaluator.

fn DescribeNumber<T>(T value) : int32 {
    static if (T is float) {
        return 1;
    }
    else if (T is double) {
        return 2;
    }
    else if (T is integer || T is unsigned || T is signed) {
        return 3;
    }
    else {
        return 0;
    }
}

A static if condition may contain only predicates of the form T is X, combined with &&, ||, !, and parentheses. T must name a generic type parameter visible in the current generic scope. X may be a concrete type, an interface, a named constraint, or any constraint qualifier (struct, class, enum, flags, numeric, integral, integer, signed, unsigned, real, or blittable).

Inside the true branch, positive facts refine the generic parameter for semantic analysis:

• T is Dog lets values of type T be used as Dog.
• T is InterfaceName and T is ConstraintName expose the corresponding members.
• T is real, T is integer, and other qualifiers expose the same constraint view as an equivalent where clause.
• A && B applies both refinements.
• A || B applies only facts common to all alternatives; for example T is real || T is integer refines T to numeric, T is signed || T is unsigned refines T to integral, and T is Dog || T is Animal refines T to Animal.
• !A is valid for branch selection, but it does not add a positive refinement.

The else branch is checked under the original generic assumptions; v1 does not apply negative refinements. Payload capture is not supported on static if.

In v1, static if branches inside a state fn may use existing state values, but they may not declare new state variables, declare state.create / state.destroy hooks, or call another state fn. Those operations register state-tree metadata during semantic analysis, before generic specialization can prune unselected branches.

During specialization, the compiler evaluates the predicate against the concrete generic arguments and lowers only the selected typed branch. Ordinary runtime if semantics and code generation are unchanged.

Advanced Constraint Features#

Type Keywords in Constraints: this and base#

Within a constraint declaration, the keywords this and base take on special meanings as types, which makes some precise generic patterns expressible. This special behavior only applies inside constraints; elsewhere, they retain their standard meanings (instance reference and parent class access).

The this Keyword (Invariant Type)

When used as a type, this represents the exact type being checked against the constraint. It enforces an invariant relationship, meaning no subtype or supertype substitution is allowed. Patterns that must preserve the exact type, like fluent interfaces or cloning, depend on this.

constraint Cloneable {
    // The Clone method MUST return the exact same type.
    fn Clone() : this;
}

constraint FluentBuilder {
    // The WithOption method MUST return the exact same type to allow chaining.
    fn WithOption(string key, string value) : this;
}

// --- Implementation ---
// When implementing, use the concrete type name, not 'this'.
class MyBuilder implements FluentBuilder {
    fn WithOption(string key, string value) : MyBuilder {
        // ... configure ...
        return this; // Here, 'this' is the instance reference.
    }
}

The base Keyword (Contravariant Parameter Type)

When used as a parameter type in a constraint declaration, base means “the checked type, or any of its ancestor types.” This allows a type to satisfy a constraint even when its method accepts a wider type than itself. base may only appear in parameter position, not as a return type.

This solves a practical problem with inherited methods. Consider a class hierarchy where comparison logic lives on the base class:

constraint Comparable {
    fn Compare(this other) : int;
}

class Animal {
    fn Compare(Animal other) : int { return this.id - other.id; }
}
class Dog extends Animal { }

With this, Dog fails to satisfy Comparable because the inherited Compare takes Animal, not Dog. Every subclass would need to redeclare the method with its exact type, even when the base implementation is correct.

Using base instead relaxes the requirement:

constraint Comparable {
    // The parameter can be the checked type or any ancestor it is castable to.
    fn Compare(base other) : int;
}

class Animal {
    fn Compare(Animal other) : int { return this.id - other.id; }
}
class Dog extends Animal { }
// Dog satisfies Comparable: inherited Compare takes Animal, which is a base of Dog. ✓

At generic call sites, base resolves to the type parameter itself, which is always safe, because passing T where T or any supertype of T is accepted is a valid upcast:

fn Sort<T>(T a, T b) where T is Comparable {
    int result = a.Compare(b);  // b is T, always valid
}

Parameterized Constraints#

Constraints themselves can be generic, so one requirement can be reused across many types.

// A constraint for a factory that can create objects of type T.
constraint Factory<T> {
    fn Create() : T;
}

// A constraint for a type that can be converted from T to U.
constraint Converter<T, U> {
    fn Convert(T input) : U;
}

// A generic method that uses a parameterized constraint.
// The type U must be a factory that can produce T's.
fn CreateAndProcess<T, U>(U factory) : T where U is Factory<T> {
    T newInstance = factory.Create();
    // ... process newInstance
    return newInstance;
}

No Default Implementations#

A constraint is a pure compile-time contract describing a type’s required “shape”. Its members may not carry a body: every member is an abstract requirement that the satisfying type must provide itself. A member body on a constraint is a compile-time error. (For runtime fallback implementations, use a default interface method instead.)

Constraint Composition and Flattening#

Constraints can be combined and extended to create more complex requirements. When you compose constraints, the compiler flattens the entire hierarchy into a single, unified set of requirements.

Conflict Resolution#

During flattening, conflicts can arise. Because constraints are satisfied by a type’s public “shape”, there is no mechanism to provide alternate implementations to resolve conflicts. Therefore, any ambiguity results in a compile-time error.

• Same Signature: Valid. Duplicate requirements are merged into one.
• Different Signatures, Same Name: Error. The compiler cannot resolve the ambiguity.

Constraint Satisfaction#

A type can satisfy a constraint in two ways:

1. Duck Typing (Implicitly): If a type has the required members with the exact matching signatures, it automatically satisfies the constraint. This is the primary mechanism.
2. Explicit Implementation: You can optionally declare that a type implements a constraint using the implements keyword. This provides no runtime benefit but serves as clear documentation and allows the compiler to validate the implementation at the type’s declaration site.

Multi-Constraint Satisfaction Example#

When a generic parameter has multiple constraints, the type argument must satisfy all requirements from the combined, flattened hierarchy.

// Define the building blocks
constraint Printable { fn Print() : string; }
constraint Comparable { fn Compare(this other) : int; }

// 'Serializable' requires 'Printable' and adds its own requirement.
constraint Serializable implements Printable {
    fn ToBytes() : byte[];
}

// This function requires a type 'T' that is BOTH Serializable and Comparable.
fn ProcessComplex<T>(T item, T other) where T is Serializable & Comparable {
    // The flattened requirements for T are: Print(), ToBytes(), and Compare().
    // All of these calls are valid.
    string text = item.Print();
    byte[] data = item.ToBytes();
    int comparison = item.Compare(other);
    // ...
}

// To be used with ProcessComplex, this struct must implement all three methods.
struct ComplexType {
    public fn Print() : string { return "Complex data"; }
    public fn ToBytes() : byte[] { return new byte[](); }
    public fn Compare(ComplexType other) : int { return 0; }
}

Nullable Arguments and the Built-in Constraints#

A nullable declares no members, so U? never satisfies a constraint by duck typing. The three built-in constraints from the standard library — Equatable, Hashable, and Comparable — are the exception: U? satisfies each exactly when U does, with the lifted null semantics. null equals null and equals no value; null hashes to one fixed value; and null orders first (null < any value, null == null). Otherwise the element’s Equals, GetHashCode, or CompareTo decides. This is what admits List<int32?>.Contains, Set<string?>, Dictionary<Key?, V>, and Sort() on a List<int32?> (nulls first). When the element fails, the diagnostic names the element. A constraint of your own that merely matches the shape does not lift — U? is refused as before — while one that includes Equatable, Hashable, or Comparable lifts exactly those members.

Detailed Generic Method Inheritance Rules#

When overriding a virtual generic method in an inheritance hierarchy, or when implementing a generic method from an interface, Wax enforces strict matching rules to maintain type safety. The signature of the override or implementation must be identical to the base definition. This includes the number of generic parameters and all of their where clause constraints in the exact same order.

abstract class Base {
    public virtual fn Sort<T>(T[] items) where T is Comparable & Cloneable;
}

class Derived extends Base {
    // ✓ VALID: Constraints match exactly in the same order.
    public override fn Sort<T>(T[] items) where T is Comparable & Cloneable { /*...*/ }

    // ✗ ERROR: Constraints in the wrong order.
    // public override fn Sort<T>(T[] items) where T is Cloneable & Comparable { /*...*/ }
}

Per-Method Constraint Refinement#

A where clause on a method can constrain not only the method’s own type parameters, but also the enclosing type’s type parameters. This allows a generic type to offer some methods that only work when the type argument satisfies additional requirements, without forcing all users of the type into that constraint.

constraint Comparable {
    fn CompareTo(this other) : int32;
}

class Container<T> {
    T? value;

    // Works for any T, with no constraint needed.
    public fn Get() : T? { return this.value; }

    // Only callable when T satisfies Comparable.
    public fn Max(T other) : T where T is Comparable {
        if (this.value.CompareTo(other) > 0) {
            return this.value;
        }
        return other;
    }
}

fn Main() {
    // int32 satisfies Comparable, so both Get() and Max() are callable.
    var ints = new Container<int32>(5);
    ints.Get();
    ints.Max(3);           // OK

    // Blob does NOT satisfy Comparable, so only Get() is callable.
    var blobs = new Container<Blob>();
    blobs.Get();           // OK
    blobs.Max(new Blob()); // ERROR: Blob does not satisfy Comparable
}

The where clause does not affect whether the type can be instantiated. Container<Blob> is valid; you just cannot call methods that require constraints Blob doesn’t satisfy.

Inside the method body, the constraint is in effect: the compiler knows T is Comparable, so calling CompareTo on values of type T is valid.

A method can constrain both its own type parameters and enclosing type parameters in the same where clause:

class Container<T> {
    public fn MapSorted<U>(fn<(T) : U> f) : List<U>
        where T is Comparable, U is Hashable {
        // T is Comparable (from enclosing type), U is Hashable (method's own)
    }
}

Naming Conventions#

By convention, interfaces and constraints are named differently to improve clarity.

• Interfaces: Start with an ‘I’ (e.g., IDisposable, IComponent).
• Constraints: End with ‘-able’ or a similar suffix describing a capability (e.g., Comparable, Cloneable).

Constraints vs. Interfaces#

Constraints and interfaces serve different purposes. Constraints are a tool for compile-time polymorphism with zero runtime cost, while interfaces are for traditional runtime polymorphism.

When to Use Each#

Use a constraint when:

• You are writing generic algorithms that need to operate on a wide variety of types.
• You need to support value types (structs) without performance penalties.
• Performance is critical and you want to avoid any runtime overhead (static dispatch).
• The exact types are known at compile time.

Use an interface when:

• You need to store different concrete types in a single, heterogeneous collection (e.g., IDrawable[]).
• You need traditional object-oriented runtime polymorphism (dynamic dispatch).
• You are working primarily with reference types (class).
• You want to define a public API contract that must be explicitly implemented.

Key Design Considerations#

A critical difference is how name collisions are handled. Interfaces allow for explicit interface implementation (fn IMyInterface.Method() { ... }) to resolve conflicts. Constraints do not have this mechanism. A type must satisfy a constraint with its public “shape”. Any ambiguity results in a compile-time error.

Wax’s memory model is the deciding factor: structs cannot be boxed. This means a struct cannot be converted to a reference type to be stored in a collection of interface instances.

• Constraints are the only way to achieve zero-cost, static polymorphism for structs.
• Interfaces are the tool for runtime polymorphism for classes.
• They are complementary. Constraints do not replace interfaces; they are the alternative for cases where runtime polymorphism is unnecessary or impossible.

Top-Level Declarations#

In Wax, not all code must live inside a class or struct. You can declare functions, constants, and global variables at the top level of a file. These declarations are fundamental for organizing code into modules, creating utility libraries, and defining global values.

Visibility and Host Communication#

Top-level declarations use a combination of keywords to control their visibility within Wax and their interaction with the host application.

Visibility Modifiers#

These keywords control whether a declaration can be accessed from other Wax code.

• public (Default): The declaration is visible and can be used by any other Wax code. If no modifier is specified, public is assumed.
• internal: The declaration is only visible to code within the same module.
• protected: The declaration is only visible to code within the same namespace.
• private: The declaration is only visible within the file it is declared in.

Host Communication Keywords#

These keywords control whether a declaration is part of the API exposed to or from the host application.

• api: Exposes a Wax function to the host application. The host can call api functions declared at top level or as members of a static class. This keyword cannot be applied to classes, structs, top-level constants, or static fields.
• host: Declares a function that is implemented by the host application, allowing Wax code to call it. host fn may also be declared inside a static class for namespace grouping.

These keywords can be combined with visibility modifiers to control both aspects.

// A function visible to all Wax modules and exposed to the host.
public api fn StartGame() { /* ... */ }

// An api function is a common way to expose a constant value to the host.
public api fn GetMaxPlayers() : int { return 4; }

// A function provided by the host, callable from any Wax module.
public host fn LogMessage(string message);

// A function provided by the host, but only callable from within this file.
private host fn LogDebug(string message);

// Static classes group related boundary functions without adding an instance receiver.
static class Console {
    api fn WriteLine(string message) { /* ... */ }
    host fn ReadLine() : string;
}

Top-Level Functions#

Functions declared outside of any type are known as top-level functions. They are useful for creating helper routines that don’t depend on the state of a specific object instance.

// A simple internal function.
internal fn CalculateDistance(Point a, Point b) : float {
    float dx = a.x - b.x;
    float dy = a.y - b.y;
    return Math.Sqrt(dx * dx + dy * dy);
}

For a complete guide to function syntax, including parameters, return values, and advanced features, please see the main “Functions in Wax” documentation.

Top-Level Constants (const)#

Use the const keyword to declare a value that is fixed at compile time. The compiler will substitute the value of a constant wherever it is used, which can lead to performance optimizations.

// A public constant, available to all Wax modules.
public const string AppName = "My Wax Application";

// An internal constant for this module only.
internal const float Pi = 3.14159f;

Because a const is substituted as a literal at each use, it holds only values that are literals: the numeric types, bool, char, string, and enums. Arrays, classes and structs are not const-able. Declare them static instead, which is the form that holds a real object:

const int32[] Sizes = new int32[] { 1, 2, 3 };    // rejected: an array is not a literal
static int32[] Sizes = new int32[] { 1, 2, 3 };   // ok

Top-Level Static Fields (static)#

For global state that can be modified at runtime, use a static field. These are global variables whose lifetime spans the entire program.

The static keyword can also be used on fields inside a class or struct, where the same rules apply.

// A global counter, visible only within this module.
internal static int32 globalCounter = 0;

// A nullable class reference, which starts as null.
private static GameState? currentState;

// Static fields on a class.
class Counter {
    static int32 instanceCount = 0;

    constructor() {
        Counter.instanceCount = Counter.instanceCount + 1;
    }
}

Once initialized, static fields can hold any value of their declared type, and they can be freely read and written at runtime like any other field. The restrictions below apply only to the declaration and initial value, not to runtime usage.

Type and Initialization Restrictions#

Declaration order is not the initialization order. The compiler first validates each initializer as either constant-safe or proven runtime-safe, records any static fields it reads, then orders statics so dependencies initialize first. Cycles in that dependency graph are rejected.

Allowed types:

A single-dimension array whose size and elements are static-initializer-safe may be non-nullable, unlike reference types in general. Its contents are fully determined before normal program execution; when an element reads another static, that dependency participates in static-initializer ordering. The element type may be a primitive, an enum, a string, or a blittable struct (no reference fields). This is the idiomatic form for lookup tables: sine tables, palettes, charset maps, vertex/transform data. A non-nullable array of this kind must have an initializer (there is no implicit default); jagged/multi-dimension arrays (int32[][]) still must be nullable.

The initializer may be an element list (new int32[] { 1, 2, 3 }), a static-initializer-safe size (new int32[N], allocating N zero-filled elements), or the two combined (new int32[N] { 1, 2 }, filling a prefix and zero-filling the remaining tail). The combined form requires the size to be at least the initializer count, and is only prefix-fillable because the element’s zero is a real value. An element type with no valid zero default (a non-null reference, or a struct bearing one) must be covered exactly.

A non-nullable class static is allowed when the compiler can prove its initializer publishes a real object before normal execution starts. The value must come from a direct new Class(...) expression, or from a statically known helper/factory method whose single return is either a freshly allocated object or another already-proven static. The full constructor/helper path must avoid host and API calls, dynamic dispatch, delegate calls, escaping recoverable throws, static writes, writes through external references, and unknown heap writes. Recoverable throws handled by an explicit catch are allowed only when the catch path itself satisfies the same rules. Unrecoverable panics do not invalidate the proof: a panicking initializer does not publish a value that later Wax code can observe. Any static values it reads participate in the same dependency ordering as constant-safe initializers, and cycles are rejected. This allows constructors and generated field initializers to read other proven statics without requiring the static slot itself to be nullable.

Disallowed types:

• Non-blittable structs, meaning structs containing reference-typed fields (e.g. string, class references), cannot be used as static fields. Their reference fields would need GC initialization, and allowing struct initializers would reintroduce circular dependency risk. Use a class static instead when reference fields are needed.
• Generic type parameters: static T value inside a generic class is not allowed, because the concrete type could be anything at instantiation time. Use static T? value instead, since nullable types always have a safe default (null).

Initializer Scope#

A static field’s initializer resolves in its declaring type’s scope. A sibling static binds by bare name, which means the same slot as the qualified spelling, and the declaring type’s generic parameters are in view, so a generic type’s initializer can name the enclosing instantiation.

Statics of a generic type get per-instantiation storage, so a generic initializer seeds from the same instantiation it belongs to: in class Box<T>, Box<int32>.b reads Box<int32>.a and Box<bool>.b reads Box<bool>.a. Reading another generic type’s static through the enclosing parameter follows the same rule. Ordering and cycle rejection apply across all of these the same way they do at top level; a cycle that exists only between two instantiations, and not between the declarations they come from, is only visible once the program is generated, so it is reported then rather than while the declaration is checked.

The enclosing type’s instance members stay out of reach: an initializer runs before any instance exists, so this, base, and bare instance field, property, and method names are rejected.

static int32 a = 100;                 // top level

static class Counter {
    public static int32 a = 4;
    public static int32 b = a + 1;    // Counter.a, not the top-level a -> 5
}

class Box<T> {
    public static int32 a = 4;
    public static int32 b = Box<T>.a + 1;   // same slot as a bare `a`
}

class Other<T> {
    public static int32 c = Box<T>.a + 2;   // this instantiation's Box<T>.a
}

Initializer Restrictions#

Static field initializers must be either constant-safe static-initializer expressions or proven runtime-safe non-null class initializers. Constant-safe initializers may contain constants and reads of other static fields; the compiler dependency-orders those static initializers and reports a cycle if no valid order exists. Proven runtime-safe class initializers may call the selected constructor, fresh-receiver object-initializer field stores/property setters, and simple helpers/factories only when their transitive effects and return value are statically proven safe. The initializer expression itself cannot contain local variable or parameter reads, this, instance state, property accessors outside the admitted fresh object-initializer setter form, or other runtime-dependent expressions whose read set or effects cannot be tracked. Constructor bodies in the proven class path may use this only for the object being initialized.

Allowed initializers:

• Literals: 42, 3.14f, true, 'A', "hello"
• Enum members: Color.Red
• Const references (resolved at compile time)
• Arithmetic on constants: 1 + 2 (const-folded by the compiler)
• Json literals: { x: 42, y: [1, 2, 3] }
• Static-initializer-safe array literals: new int32[] { 1, 2, 3 }, new string[] { "a", "b" }, a sized array new int32[4] (zero-filled), and arrays of blittable struct literals new Vec2[] { new Vec2 { .x = 1, .y = 2 } }
• Blittable struct object-initializers: new Vec2 { .x = 1, .y = 2 }, the parameterless form new Vec2(), and the combined form new Vec2() { .x = 1 } (every field value must itself be static-initializer-safe)
• Reads of other static fields, including inside arithmetic, json literals, array literals, and blittable struct object-initializers, when the dependency graph is acyclic
• Runtime-safe non-null class construction, such as static Settings settings = new Settings();, when the constructor/helper path satisfies the proof above
• Runtime-safe non-null class object-initializers, such as static Settings settings = new Settings { .Value = LoadDefault() };, when every field value and property setter is proven safe for the freshly constructed object. An object-initializer assignment to a reference-storing field or an earlier property setter does not prove deep ownership for later setter writes through that field.
• Runtime-safe factory/helper calls that return a fresh non-null class object or another already-proven static
• null (for nullable types)

Not allowed:

• Method calls for constant-safe values: static int32 x = ComputeValue();
• Method or factory calls whose effects or return provenance are not proven safe
• Parameterized constructor calls for blittable structs: static Vec2 origin = new Vec2(0, 0);. Use the object-initializer form new Vec2 { .x = 0, .y = 0 } instead
• Class object-initializer/property-setter forms whose effects are not proven safe for the fresh object, including virtual/interface setters, setters that write statics, call host/API functions, use dynamic dispatch, write through external references, or rely on getter-returned external aliases as owned state
• Local variables, parameters, this, instance fields, and property accessors
• Static dependency cycles: static int32 a = b; static int32 b = a;
• Any expression that could depend on untracked runtime state

// Valid static fields.
static int32 count = 0;
static string greeting = "hello";
static float pi = 3.14159f;
static json config = { debug: false, maxRetries: 3 };
static MyClass? instance;

// Non-nullable static-initializer-safe arrays (lookup tables) and blittable struct values.
static int32[] sineLut = new int32[] { 0, 70, 100, 70, 0 };
static string[] names  = new string[] { "ada", "alan" };
static Vec2[] points   = new Vec2[] { new Vec2 { .x = 1, .y = 2 }, new Vec2 { .x = 3, .y = 4 } };
static Vec2 origin     = new Vec2 { .x = 0, .y = 0 };

// Static reads are dependency-ordered, not declaration-ordered.
static int32 maxRetries = retryBase + 2;
static int32 retryBase = 3;

class StaticSettings {
    public int32 retries;

    public constructor() {
        this.retries = retryBase;
    }
}

static StaticSettings settings = new StaticSettings();

fn MakeSettings() : StaticSettings {
    return new StaticSettings();
}

static StaticSettings factorySettings = MakeSettings();

// At runtime, statics can be assigned freely.
fn Init() {
    instance = new MyClass();
    greeting = "goodbye";
    count = 100;
}

// Invalid: these would be compile errors.
// static int32 x = GetValue();        // method call
// static Vec2 origin = new Vec2(0,0); // struct constructor call
// static MyClass obj;                 // non-null class static needs a proven initializer
// static MyClass bad = MaybeGet();    // return value or effects not proven safe
// static NonBlittableStruct s;        // non-blittable struct not allowed
// static int32 a = b; static int32 b = a; // static cycle

Type Declarations and Imports Are Top-Level Only#

A type is scoped by the namespace it is declared in, never by an enclosing type. Wax has no nested type: class, struct, interface, enum, flags, error, constraint, host channel, and api channel are all top-level declarations, and there is no Outer.Inner name to reach one by. An import is top-level for a related reason: it binds a name for the whole file, not for one type’s body.

Written inside a type body, each of these is refused by name rather than treated as a member: ERR_TypeDeclarationMustBeTopLevel, ERR_ImportMustBeTopLevel, and ERR_ChannelMustBeTopLevel. Declare the type beside the one that would have contained it. Everything that could have named it from inside still can, because both live in the same namespace.

The rule runs the other way too. A constructor and an enum case each name something about the type that declares them, so both are members and nothing else; a top-level one is refused with ERR_ConstructorMustBeAMember and ERR_EnumCaseNotAllowedHere. A top-level function is spelled fn.

import List from Wax;

class Inner {
    public int32 x;
}

class Holder {
    public fn Make() : int32 {
        Inner i = new Inner();      // Inner is a sibling, and visible here
        return i.x;
    }
}

// Invalid: these would be compile errors.
// class Outer { class Nested { int32 x; } }   // ERR_TypeDeclarationMustBeTopLevel
// class Outer { import List from Wax; }       // ERR_ImportMustBeTopLevel
// class Outer { host channel Slots { int32 x; } }  // ERR_ChannelMustBeTopLevel
// class Outer { api channel Results { int32 x; } } // ERR_ChannelMustBeTopLevel
// constructor() { }                           // ERR_ConstructorMustBeAMember
// case Red;                                   // ERR_EnumCaseNotAllowedHere

Modules, Namespaces, and Imports#

Wax uses modules and namespaces to organize code and prevent naming conflicts.

• Modules: A module is a self-contained unit of Wax code. Package modules have a unique registry identity and may also be given an importer-local alias.
• Namespaces: A file can optionally declare a namespace, which must be the first statement in the file. This namespace is relative to the module’s root. If a file doesn’t declare a namespace, its contents belong to the module’s default root namespace. Namespaces can be nested using ::.
• Imports: To use a declaration from another namespace, you must import it using the import keyword. Multiple symbols can be imported in a single statement using comma separation.

// In a file within a module named 'Gfx':
// This declaration must be at the top of the file.
namespace Paint::Textures; // The full namespace is Gfx::Paint::Textures

public class Texture2D { /* ... */ }
public fn LoadTexture(string path) : Texture2D { /* ... */ }

// ---

// In another file within the *same* 'Gfx' module:
// You can optionally omit the module name for same-module imports.
import Texture2D from ::Paint::Textures;

// ---

// In a file within a *different* module (e.g., 'App'):
// You must use the fully-qualified path.
import Texture2D, LoadTexture from Gfx::Paint::Textures;

// Now you can use the imported declarations directly.
var tex = LoadTexture("image.png");

Package dependencies can be addressed through the alias declared by the importing module or through an exact scoped identity. Exact identities are useful when aliases would be ambiguous. Package aliases begin with an uppercase ASCII letter. Durable package identities are lowercase ASCII words joined by single dots or hyphens, with every word beginning in a letter. Exact identities in Wax source are ASCII case-insensitive before ::; TitleCase words are recommended. Namespace names after :: remain case-sensitive.

When a project contains wax.lock, the compiler validates its package graph schema and verifies that the recorded SHA-512 hash matches the exact wax.json bytes before discovering package modules. Any manifest edit makes the lock stale until wax update records a new graph.

import Vector from Math::Linear;
import Matrix from @Wax/Math-Tools::Linear;

Import Aliasing#

To resolve naming conflicts or to use a shorter name for an imported type, you can use the as keyword to create an alias.

// Assume both modules define a 'Button' class.
import Button from MyEngine::UI;
import Button as GfxButton from Gfx::Widgets;

// Now the names are unambiguous.
var uiButton = new Button();
var gfxButton = new GfxButton();

Advanced Imports#

Just as with member access, it is possible to bypass the visibility rules when importing. This is highly discouraged outside of unit testing but is provided as a “sharp knife” when necessary. When using these features, you become responsible for their usage, i.e. library authors should always assume nobody is doing this and design their apis accordingly with appropriate modifiers, and should not be held accountable for non-public breaking changes.

• Protected Imports: To import a protected symbol from another namespace, use the protected keyword at the beginning of the statement.

  import protected MyType from Gfx::Paint::Internal;
  

• Internal Imports: To import an internal symbol from another namespace, use the internal keyword at the beginning of the statement.

  import internal MyType from Gfx::Paint::Internal;
  

Error Handling#

Wax’s error handling system is designed to be explicit, safe, and performant. It distinguishes between two classes of abnormal control flow: recoverable errors and unrecoverable panics.

An error represents a recoverable problem that is an expected part of program execution, such as a file not being found or a network connection failing. Functions that can produce errors must declare them as part of their signature. To maintain high performance, errors do not capture stack traces unless they are unhandled and are promoted to a panic.

A panic, on the other hand, represents a critical, unrecoverable bug in the program’s logic, like accessing an array out of bounds. Panics are triggered by the panic statement, which terminates the app immediately rather than raising a value that some caller could intercept. A panic’d app will not run again; the host application will need to restart it if it should continue. An unhandled error that propagates to the root of the call stack will also escalate into a panic.

Declaring Errors#

In Wax, an error is a specialized kind of reference type designed for recoverable failure conditions. The error keyword provides a clear, concise syntax for defining these types. Functionally, an error is a frame-scoped class that implicitly inherits from a built-in base error type. Errors can have fields, properties, constructors, and methods, and can form their own inheritance hierarchies; their lifetime is managed automatically by the frame-based memory system.

error FileError {
    public string path;
    public string message;
    
    constructor(string path, string message) {
        this.path = path;
        this.message = message;
    }

    // Errors can have methods to provide additional context or helpers.
    public fn GetDisplayMessage() : string {
        return "File Error on '${this.path}': ${this.message}";
    }
}

// Errors can extend other errors to create a hierarchy.
error HttpError extends NetworkError {
    public string responseBody;
    
    constructor(string endpoint, int statusCode, string body) 
        : base(endpoint, statusCode) {
        this.responseBody = body;
    }
}

Panicking#

panic terminates the app. It is a statement, not a throw: there is no Panic value, nothing for a catch to match, and no throws declaration required. A panic is legal in any function, including one that declares no errors at all.

A panic raised inside an api fn call unwinds to that API boundary and is reported to the host as a WxError; see Panics and the Host below. Anywhere else, meaning during startup, in frame-end work, or on the wasm backend, a panic terminates the process outright. Either way the app is finished; the difference is only whether a host survives to be told about it.

// Trigger a panic explicitly when an invariant is violated.
if (index < 0) {
    panic("Index must be non-negative, got $index");
}

It takes one or two string arguments: a message, and an optional detail string carried alongside it.

panic("bad state");
panic("bad state", "expected a non-zero capacity");

Because a panic never returns, it diverges. It satisfies a non-void return on its own, and it can be used anywhere a diverging term is allowed, such as the right-hand side of ?? or one arm of a ternary.

fn Lookup(string key) : string {
    panic("not implemented");           // stands in for the string return
}

string got = maybe ?? panic("missing");

unreachable is the sibling form, for a branch the programmer asserts can never execute. It takes an optional single string argument and panics if it is ever reached.

unreachable;
unreachable("regex VM produced an unknown opcode");

The runtime panics on its own for conditions like out-of-bounds array access, divide by zero, a failed forced cast (as!), and dereferencing or force-unwrapping a null (!). Note that ordinary +, -, and * wrap on overflow rather than panicking.

Function Error Declarations#

Functions must explicitly declare all recoverable errors they can produce using the throws keyword in their signature. This makes a function’s potential for failure a part of its contract.

Specific Errors#

A function declares the set of specific error types it can throw, separated by |. This is the most common and recommended form, because it gives the caller a precise, typed contract.

// This function can throw either of two specific error types.
fn FetchData(string url) : string throws NetworkError | TimeoutError {
    // ... implementation that can throw either error
}

A declared set names failure modes that need not be related to each other. Where they are related, subtyping composes with it: catch coverage is by supertype, so a function that declares throws NetworkError may throw any subtype of it, and a caller may catch either the base or a specific subtype.

error NetworkError { }
error TimeoutError extends NetworkError { }

fn Fetch(string url) : string throws NetworkError {
    throw new TimeoutError();          // a NetworkError, so the contract holds
}

fn Load(string url) : string throws NetworkError {
    // Handle just the timeout; any other NetworkError propagates.
    return try Fetch(url) catch TimeoutError |te| { yield ""; };
}

A single try may also see more than one error type because the expression it covers calls several different functions. Both routes feed the same typed catch clauses below.

A declared set is a promise about which types can leave the function, and callers rely on it: a set of typed catch clauses covering it is exhaustive on its own, with no untyped catch to fall back on. So every throw must name a value the compiler can place in the set. A value known only to be the base error type cannot be placed, even when it happens to hold a member at runtime, and is rejected.

fn Widened() : string throws NetworkError | TimeoutError {
    Error e = new TimeoutError();
    throw e;            // ✗ ERROR: only known to be `Error`, though it holds a member
}

fn Branching(bool useA) : string throws NetworkError | TimeoutError {
    throw useA ? new NetworkError() : new TimeoutError();
                        // ✗ ERROR: the two arms meet no lower than `Error`
}

fn Fixed(bool useA) : string throws NetworkError | TimeoutError {
    if (useA) { throw new NetworkError(); }   // ✓ each throw names its own type
    throw new TimeoutError();
}

Bare throws accepts all of these, because it promises nothing narrower than “some error” and so obliges the caller to handle everything.

Generic Errors#

In some cases, you may want to declare that a function can throw any error. This can be done with a generic throws clause. This is less type-safe but can be useful for simple scripts or highly generic functions.

// These two declarations are equivalent. They state that the function
// can throw any type of error.
fn RiskyOperation() throws {}
fn AnotherRiskyOperation() throws error {}

A function with no throws declaration at all cannot throw an error. It must handle all potential errors from functions it calls internally.

Handling Errors with try-catch Expressions#

Operations that can throw an error must be invoked with the try keyword. The try-catch construct is an expression, meaning it evaluates to a value. Both the try block and all catch blocks must produce a type that is compatible with the expression’s result type.

fn GetValue() : string {
    string content = try ReadFile("data.txt") catch |err| {
        // NOTE: 'return' exits the entire GetValue function.
        // To provide a value just for the try-catch expression, use 'yield'.
        Debug.Log("Failed to read file: ${err.message}");
        return "default content"; 
    };
    return content;
}

The yield Keyword#

Within a catch block, the yield keyword provides a concise way to return a value from the enclosing try-catch expression, effectively ending the catch block’s execution at that point. This is distinct from return, which exits the entire containing function.

// Using yield to return from the try-catch expression.
string result = try ReadFile("config.json") catch |e| {
    yield "default_config";  // Returns this value from the try-catch expression.
};

// Conditional yield for more complex logic.
string data = try FetchData(url) catch |e| {
    if (e.statusCode == 404) {
        yield "not_found";  // Early return from catch block.
    } 
    else {
        LogError(e);
        yield "error_default";
    }
};

What yield may carry follows the try it belongs to. A try that produces a value requires yield <value>; a bare yield there has nothing to supply and is rejected. A try used as a plain statement produces no value, so the reverse holds: a bare yield exits the catch early, and supplying a value is rejected.

// Statement-context try over a void call: bare yield leaves the catch early.
try DangerousOperation() catch |e| {
    if (CanRecover(e)) {
        yield;                  // done handling it; carry on after the try
    }
    panic("Unrecoverable error: ${e.message}");
};

Typed catch Blocks and Exhaustiveness#

To handle different error types gracefully, you can provide multiple, typed catch blocks. The compiler enforces exhaustiveness, meaning all error types declared in the function’s throws signature must be handled.

To ensure exhaustiveness, unhandled errors must either be propagated (by adding them to the containing function’s throws clause) or caught by a final, untyped catch |e| block.

The compiler knows the complete set of error types a try body can produce: every call in it declares its throws set, an override must declare the same throws set as the member it overrides, and panics are not catchable values. Coverage is by supertype, so catch NetworkError covers a thrown TimeoutError extends NetworkError, and a set of typed catches covering every type in that set is exhaustive on its own.

“Propagate the rest” and “handle all of it here” are both complete. When the typed catches leave an error type unhandled and the containing function’s throws clause accepts it, an error matching no clause is raised to the caller: the try does not fall through, and the statements after it do not run. That path leaves the function, so it owes a try expression no value, and a final untyped catch |e| is not required to satisfy the value analysis either.

This is what makes a clause set that is deliberately partial safe. Handling one specific error and leaving the rest to the caller is the same guarantee as handling none of them: the error always reaches someone.

fn Load(string url) : string throws NetworkError {
    // TimeoutError is handled here; any other NetworkError is raised to our
    // caller, so `Decorate` is not reached for one.
    string body = try Fetch(url) catch TimeoutError |te| {
        yield "";
    };
    return Decorate(body);
}

Coverage is decided on the declared types, so a clause naming a subtype of a declared thrown type (catch TimeoutError against a throws NetworkError callee) handles that subtype and propagates the rest, exactly as above. If the containing function declares no compatible throws, there is nowhere to propagate to and the unhandled type is a compile error instead.

A clause whose type is unrelated to every type the try can produce, being neither a supertype nor a subtype of any of them, can never run, and the compiler warns that it is dead code. Both relations count as live: catch NetworkError is live against a thrown TimeoutError because it catches it, and catch TimeoutError is live against a declared throws NetworkError because the value may be exactly that subtype. An untyped catch |e| catches everything and is never dead.

// This function handles all possible errors from FetchData locally.
fn GetHomepage() : string {
    string data = try FetchData("api.example.com")

    // This block only executes for a NetworkError.
    catch NetworkError |ne| {
        yield "Site is down, please try again later. (Code: ${ne.statusCode})";
    }

    // This block only executes for a TimeoutError.
    catch TimeoutError |te| {
        yield "Connection timed out. Please check your network.";
    }

    // Since FetchData can only throw NetworkError or TimeoutError, and both
    // are handled, the compiler knows this is exhaustive. A final untyped
    // catch is not needed here.

    return data;
}

Error Propagation and Rethrowing#

Errors can be propagated up the call stack or rethrown after partial handling.

• Implicit Propagation: A try without a catch block automatically propagates any thrown error to its caller. The calling function’s throws signature must be compatible. This can be combined with return for concise propagation.
• Explicit Rethrowing: Use the throw keyword inside a catch block to re-propagate an error or to translate one error type into another.

// Implicit propagation can be written concisely.
fn LoadConfiguration() : string throws FileError {
    // Any FileError from ReadFile is propagated to the caller.
    return try ReadFile("app.config");
}

// Translating an error
fn ProcessFile(string path) : string throws ProcessError {
    string content = try ReadFile(path)
    
    // Catch the specific error from ReadFile...
    catch FileError |fe| {
        // ...log it, and throw a new, more specific error.
        LogError("Underlying file error: ${fe.message}");
        throw new ProcessError("Failed to process file contents from $path");
    };
    
    return content;
}

Chaining Failable Operations#

The try keyword applies to an entire expression chain. If any part of the chain fails, the expression aborts and control transfers immediately to the catch block.

class DataProcessor {
    fn LoadData() : DataProcessor throws FileError { /* ... */ return this; }
    fn ValidateData() : DataProcessor throws ValidationError { /* ... */ return this; }
    fn ProcessData() : string throws ProcessError { /* ... */ }
}

// This function must declare all unhandled errors from the chain.
fn RunProcessor() : string throws ProcessError {
    string result = try new DataProcessor()
        .LoadData()     // Can throw FileError
        .ValidateData() // Can throw ValidationError
        .ProcessData()  // Can throw ProcessError
    
    // Handle FileError specifically
    catch FileError |fe| {
        yield "Default result: File error";
    }
    
    // Handle ValidationError specifically
    catch ValidationError |ve| {
        yield "Default result: Validation error";
    }

    // ProcessError is not handled, so it is allowed to propagate
    // because the function signature includes 'throws ProcessError'.
    
    return result;
}

Error Handling in Inheritance#

When overriding a method that throws, an override may declare the same throws set or a narrower one – a subset of what the base declares. It may not add an error type the base does not declare, as that would break the caller’s ability to exhaustively handle all possible errors. Narrowing is safe for every caller: code holding the base type already handles the full base set, so the clauses for errors the override cannot raise simply never run, while code holding the concrete type sees the smaller, honest set.

Narrowing stops short of dropping throws entirely. A throwing and a non-throwing method have different call signatures, and a virtual call goes through the base method’s signature – so an override must still declare throws, even when it raises fewer errors than the base.

abstract class DataSource {
    abstract fn Load() : string throws FileError | NetworkError;
}

class FileDataSource extends DataSource {
    // ✓ VALID: the same error signature.
    override fn Load() : string throws FileError | NetworkError {
        // ...
    }
}

class LocalFileSource extends DataSource {
    // ✓ VALID: narrowing. Reading a local file cannot raise a NetworkError, and
    // saying so is safe for every caller.
    override fn Load() : string throws FileError {
        // ...
    }
    
    // ✗ ERROR: cannot widen the error signature with a type the base never declares.
    // override fn Load() : string throws FileError | ParseError { }
}

Best Practice: It’s often better to avoid overriding throwing functions when possible. Consider using non-virtual methods or composition for operations that can fail, as it leads to simpler contracts.

Stack Traces and Performance#

Wax prioritizes performance in its error handling design. Throwing and catching a recoverable error costs nothing beyond the branch: an error value carries no stack trace, and none is captured on the throw path.

A recoverable error is returned as an ordinary value rather than unwound, so an error path is just a return: each function’s epilogue pops its own trace entry and nothing extra is needed.

A trace is still available at a panic, because the runtime maintains a lightweight call-depth trace stack rather than reconstructing one after the fact. Each entry records a function id, an iteration count, and a line/column, so pushing and popping it costs a couple of stores per call. A panic jumps straight to the api fn boundary and skips every callee epilogue, which is exactly why the stack still holds the full depth when it lands. The boundary formats the trace first, then restores the depth it snapshotted on the way in.

Trace recording is always on in the native/C backend. A release build is not debuggable, so it drops the work it can prove is dead: a function whose emitted body makes no call and contains nothing that can raise carries no trace ops at all. Any call disqualifies that elision, because the callee may raise.

The wasm backend carries no in-module trace instrumentation, so Debug.StackTrace() returns an empty string there. This pairs with the fact that a wasm panic traps rather than reaching a host boundary.

When a panic reaches an api fn boundary, the trampoline reports it to the host as a WxError, and the host can then request the formatted trace. Because the trace stack is live at the moment of the panic, producing it requires no replay. Replaying a frame from a snapshot is a separate and far more expensive facility that exists for time-travel debugging, not for stack traces.

Interaction with the Host Application#

The error handling system described here is entirely self-contained within the Wax environment. To maintain a clean and explicit boundary, the error system does not cross into the host application.

• Error handling at the boundary uses WxError. Every api fn has an implicit WxError* parameter in the generated C signature. If the Wax function panics or throws an unhandled error, it is caught at the boundary trampoline and written to the WxError*. host fn declarations can optionally be marked throws, which adds a WxError* parameter to the generated signature that the host can write to signal failure. The Wax side must try such calls. See the Host Communication chapter for details.
• Panics and the Host: A panic raised during an api fn call is caught at that API boundary trampoline and reported as a WxError with error type "panic", leaving the host process intact. This covers panics in host-invoked Wax code, which is nearly all of it; a panic with no boundary armed terminates the process, which covers startup, frame-end work, and the wasm backend (which traps instead). After a caught panic the host can optionally request diagnostic information. That includes the stack trace, read straight off the live trace stack, and a snapshot of the Wax memory state at the time of the panic, which can be used for later replay and debugging.

Best Practices#

1. Handle errors close to the source. Propagate errors only when the caller has better context to handle them.
2. Use specific, structured error types. This allows for more granular and intelligent error handling in catch blocks.
3. Design APIs to minimize the error handling burden on the caller by handling errors internally when it makes sense.
4. Use typed catch blocks to handle different errors differently and improve code clarity.

The json Type#

The json type is a special-purpose reference type designed for working with loosely-structured, dynamic data. Its primary use case is for safe and convenient data exchange with the host application. You represent and manipulate data with a familiar, JSON-like syntax, without the strictness of structs or classes.

JSON Literals#

You can create json objects directly in code using literals.

Object and Array Literals#

The most common way to create a json value is with the object ({...}) and array ([...]) literal syntax. A key difference from standard JSON is that property keys do not require quotes.

json config = {
    // Keys are unquoted identifiers
    name: "MyApp",
    version: 1.2,
    features: ["logging", "analytics", "debugging"],
    database: {
        host: "localhost",
        port: 5432
    },
    metadata: null
};

Primitive Literals#

You can also create a json value directly from any primitive literal (string, number, bool, or null). This is useful for representing simple values within the json type system.

json name = "Alex";
json score = 100;
json isAdmin = true;
json data = null;

Accessing Data#

Accessing data within a json object is designed to be safe by default. All property and array access operations return a value of type json. If a key or index does not exist, the returned json value will represent null.

Property Access#

You can access object properties using either dot notation or bracket notation with a string key.

json user = { name: "Alex", score: 100 };

// Dot notation
json name = user.name; // Returns a json value containing "Alex"
json score = user.score;   // Returns a json value containing 100
json email = user.email; // Returns a json value containing null

Array Access#

You can access elements in a json array using numeric indexing.

json data = { values: [10, 20, 30] };

json firstValue = data.values[0]; // Returns a json value containing 10
json outOfBounds = data.values[3]; // Returns a json value containing null

Null-Safe Chaining#

A key feature of json access is that it is null-safe. You can chain multiple accessors together without checking for null at each step. If any part of the chain is null or doesn’t exist, the entire expression gracefully evaluates to a json value containing null.

json config = { database: { host: "localhost", port: 5432 } };

// This chain is safe. Since 'connection' does not exist,
// the expression evaluates to a json value containing null.
json poolSize = config.database.connection.pool.maxSize;

// This null-safety composes directly with implicit conversion.
// The result is null because the path is invalid.
int? poolSizeAsInt = config.database.connection.pool.maxSize;

Spread in JSON Literals#

The spread operator (...) can be used inside JSON array and object literals to merge values from an existing source into a new literal.

Spreading into Arrays#

You can spread a json value (expected to be an array) or a typed array into a JSON array literal.

json head = [1, 2, 3];
json extended = [...head, 4, 5]; // [1, 2, 3, 4, 5]

// Multiple spreads
json a = [1, 2];
json b = [3, 4];
json merged = [...a, ...b, 5]; // [1, 2, 3, 4, 5]

// Spread a typed array; elements are automatically wrapped to json
int32[] scores = [] { 90, 85, 92, };
json data = [...scores, 100]; // [90, 85, 92, 100]

Spreading into Objects#

You can spread a json value (expected to be an object) into a JSON object literal. When the same key appears multiple times, the last value wins.

json defaults = { theme: "dark", fontSize: 14, lang: "en" };
json userPrefs = { ...defaults, fontSize: 18, lang: "fr" };
// Result: { theme: "dark", fontSize: 18, lang: "fr" }

// Multiple spreads
json a = { x: 1, y: 2 };
json b = { y: 3, z: 4 };
json merged = { ...a, ...b }; // { x: 1, y: 3, z: 4 }

Spread Type Requirements#

• Array spread: The source must be either a json value or a typed array (T[]). Spreading other types is a compile-time error.
• Object spread: The source must be a json value. Only json objects can be spread into object literals.

Mutability#

json objects are mutable. You can add, remove, or change properties after the object has been created. Because json is a dynamic type, you can also change the type of a value stored in a field at will.