Synth Language Reference

Synth is an AI-native programming language that transpiles to JavaScript. It is designed from the ground up to be written, read, and reasoned about by language models — with unambiguous grammar, intent-first declarations, constraint-enforced types, and explicit effect tracking.

At a glance

Quick Start

Synth ships as a Node.js CLI. Install from npm or build from source, then run the bootstrap compiler against any .syn file.

Hello, Synth

Design Goals

Functions

All functions in Synth are declared with fn. The :: separator introduces the full type signature. Functions are first-class values and can be passed as arguments or returned from other functions.

Full-form function

The canonical form uses :: to separate the name from the typed signature, with the body in a block.

Short-form function v0.5 expanded

When the body is a single expression, use = expr to eliminate the block. An optional return-type annotation is supported with ->. A block body { ... } is also valid without the :: sigil.

Nested functions v0.5

A fn declaration inside a block body is emitted as a let-bound lambda — a local helper scoped to the enclosing function.

Lambda expressions

.field accessor shorthand

A bare .fieldName in any expression position is syntactic sugar for a single-argument lambda that accesses that field. Chained access is supported.

Types & Constraints

Synth's primitive types map directly to JavaScript. Type aliases add names; where clauses add runtime-enforced predicates.

Primitive types

Type aliases

Constrained types with where

Any type alias can carry a where predicate. For constrained parameters, the compiler may emit __validate_* helpers at function entry.

Records

Records are named structured data types — plain objects with known fields. They have no methods and carry no behaviour; that belongs in standalone functions.

Immutable updates

Records are updated functionally. The spread operator returns a new record with changed fields; the original is untouched.

Enums

An enum declares a closed set of named string values. It compiles to a frozen, immutable object — safe to use as a constant, in pattern matching, and across module boundaries.

Enum pattern matching

Use the Enum.Variant syntax inside a match expression.

Generated output

Tagged Unions

Tagged unions (also called sum types or algebraic data types) express a value that is exactly one of several named variants. They are the preferred replacement for inheritance hierarchies.

Pattern Matching

match is an expression, not a statement. Every arm produces a value. The checker warns when a match is not exhaustive unless a wildcard arm is present.

Basic patterns

when guards

Any arm can carry a boolean guard. Guards have full access to names bound by the pattern.

Tagged union patterns

Pattern types

likely arms v1.1

Soft classifiers inside match. Exact / hard arms are tried first; then all likely claims compete via the host embedding API; then _ fallback. Default threshold is 0.28. Claims are string phrases that describe the intent — not regexes.

Pipelines

The pipeline operator |> threads a value through a sequence of transformations. Each step receives the previous step's result as its first argument.

|> as name — named intermediate results

Any pipeline step can be named with as. When present, the entire pipeline emits as an IIFE block with const bindings, making intermediates available for reuse or debugging.

Destructuring

Destructuring let unpacks object and array values into named bindings in a single statement.

Strings

Template literals `…${expr}…` v1.0

Backtick template literals support full Synth expression interpolation — arithmetic, function calls, stdlib method syntax, anything. Each ${…} is parsed and compiled as a Synth expression, so ${items.count()} correctly compiles to ${$count(items)}. Templates may span multiple lines. This is the recommended interpolation syntax.

String interpolation "{ident}"

Any quoted string containing {ident} or {ident.prop} is automatically treated as an interpolated string. Limited to bare identifiers and property chains — for arbitrary expressions, use template literals.

Triple-quote strings """..."""

Multiline string literals that preserve newlines exactly. A leading newline immediately after """ is stripped for idiomatic alignment. Support the same {ident} interpolation as regular strings. Compile to JavaScript template literals.

Optional Chaining & Nullish Coalescing

Safe navigation through potentially-null values without nested conditionals.

Control Flow

Result Type & ? Propagation

Synth has a built-in Result<T> tagged union for explicit error handling. Construct values with ok() / err(), consume them with match or stdlib helpers, and chain fallible calls cleanly with the ? propagation operator.

Constructing and consuming Result

? — early-return on Err

Purity & Totality

House style: write annotations above the function (@pure, @intent, … then fn), not inside the body. That works for both short = forms and braced bodies, and keeps metadata visible before the signature.

@pure declares that a function has no side effects — it should not access globals, mutate state, or call effectful methods. The checker verifies this and emits warnings on violations.

@total documents that a function is defined for all inputs. It is a declaration for readers and downstream tools — not currently enforced by the checker.

Intent

The single most important annotation in Synth. @intent is a machine-readable natural language description of what a function is for — not what it does mechanically, but why it exists. It lives in Synth source today; JSDoc emission is planned for a future release.

Effects

Declares the set of side effects a function produces. As of v1.0.1, the checker warns when an async fn lacks an @effects declaration. It does not yet verify that the body matches the declared effect list.

Memoization

Wraps a @pure @total function in a Map-based memoization cache at compile time. Results are cached after the first call; subsequent calls with the same arguments return instantly.

Exhaustiveness

Opt-in exhaustiveness checking for functions whose body is a match expression. Place @exhaustive on the line(s) above the function — the checker verifies that all variants of a tagged union are covered.

Tests

Top-level inline test declarations. Tests are registered in __synth_tests at runtime and can be run via __runSynthTests() in the browser, or the CLI --test flag.

Fallible Functions

Mark a function as fallible. @throws fn f() -> Result<T> signals to the checker and to callers that this function may return Err. The static checker warns if a @throws result is silently ignored without a match or ? operator.

Standard Library

The callable surface of Synth — every helper in synth.stdlib.js. Generated JS uses a $ prefix (e.g. map → $map). Most list and string functions also support method syntax: xs.map(f) compiles to $map(xs, f).

Validation presets

Built-in regex presets used with constrained string types (e.g. type Email = string where value matches email). Defined as __synth_presets in the stdlib.

CLI

Spec Extraction

synth --spec walks the AST and emits a JSON document agents can query — no need to re-parse bodies for intent metadata. Schema version 0.1 (freeze to 1.0 at v2.0).

Top-level shape:

Per module:

Numeric Literals

Synth v0.9.5 extends numeric literals with underscore separators, hexadecimal 0x…, and binary 0b… prefixes. Separators are stripped at compile time; the notation is preserved in generated JS output.

New CLI Commands

Static analysis and formatting ship with the v1.0.1 bootstrap toolchain.

synth --check

Runs the static checker without emitting any output file. Useful in CI or as a pre-commit hook.

$ synth --check src/main.syn
✓  main.syn — no issues

$ synth --check src/main.syn
  WARNING [line 14]: @pure function 'render' accesses effectful global 'console'

synth --fmt

Canonical formatter. Normalises 2-space indentation, spacing around operators (=, ->, =>, ::, |>, binary arithmetic), brace padding, and trailing whitespace. Does not modify </> spacing to preserve generic type parameters. Rewrites the source file in-place.

$ synth --fmt src/main.syn
✓  main.syn — formatted
✓  main.syn — already canonical     # if no changes needed

Browser Compiler API

compiler.bootstrap.js is a self-contained IIFE bundle that runs the full Synth bootstrap compiler client-side. Load it in any web page — no server, no build step, no dependencies.

<script src="compiler.bootstrap.js"></script>
<script>
  const { js, errors, warnings } = SynthCompiler.compile(source);
</script>

SynthCompiler.compile(source)

Transpiles an Synth source string to JavaScript. Always returns an object — never throws.

Error object shape

SynthCompiler.check(source)

Runs only the static checker. Returns { warnings, errors }. Useful for lightweight lint-on-type without full codegen.

SynthCompiler.stdlib / SynthCompiler.backend

SynthCompiler.stdlib is the stdlib JS source string bundled with the compiler. SynthCompiler.backend is "bootstrap" for this bundle.

SynthCompiler.version

String — the compiler version, e.g. "1.0.0".

Modules

Split a project across multiple .syn files. Use import to bring names into scope and export to mark declarations as public.

The bundler resolves imports depth-first, topo-sorts modules so dependencies come before dependents, and emits a single JS file with the stdlib included once at the top. All bundled code shares a single flat scope — no runtime module system overhead.

refine

refine x: "prose claim" is an AI-native semantic narrowing statement. It annotates a binding with a human-readable constraint that is too nuanced for a type signature — emitted as structured JSDoc and queryable by AI tooling. It compiles to a no-op comment at runtime; the value is unchanged.

Generic Type Parameters

Add type parameters to record, fn, and type declarations using angle-bracket syntax. Type parameters are erased at compile time — no runtime overhead.

Generic records

Generic functions

Generic type aliases

Interfaces

Declare structural type contracts with interface. Any record that carries the required fields and methods satisfies the interface — no explicit implements keyword needed. Interfaces are emitted as JSDoc @interface comments.

fn(T) -> U Function Types

Function types are first-class in Synth. Use fn(A, B) -> C syntax anywhere a type is expected — in record fields, interface definitions, and generic function signatures.

let infer

let infer x = expr is an AI-native annotation that signals the type of a binding should be resolved from context by the model — not written explicitly by the programmer. It compiles to an ordinary let with no runtime difference.

store

store Name { field: Type = default } declares a reactive mutable state container — an explicit effects boundary that separates pure logic from observable state. Getters expose each field; .set(patch) updates state and notifies all subscribers atomically.

async fn & await

Prefix any function declaration with async to make it asynchronous. Inside an async fn, use await expr to resolve a Promise without blocking. The stdlib provides delay(ms) for timer-based pauses.

on StoreName.change { … }

on StoreName.change { body } is syntactic sugar for registering a reactive subscription. The body runs once immediately when the subscription is registered, then again after every StoreName.set(…) call. Multiple subscriptions can target the same store.

Keywords & Annotations

Reserved words from the lexer, plus contextual forms and annotations. This is the complete roster for the current language version.

Lexer keywords

These are reserved by keyword_type in the lexer. Do not use them as ordinary identifiers (variable names, record fields, type names). Parameter names are an exception — fn f(type: string) is allowed.

Contextual keywords

Parsed as identifiers, but special-cased at declaration sites. Safe as ordinary names outside those forms — still treat them as reserved in practice when generating code.

Annotations

Written above fn (house style). Not keywords — they are @-prefixed attributes checked or recorded by the compiler.

Built-in type names

Colored as types by highlighters; they are ordinary identifiers in the lexer. Prefer not to shadow them.

Version History

Roadmap to v2.0

v1.2 shipped synth --spec. Next up is explain blocks, then the LSP and debug loop through v2.0. Past releases live in Version History.