---
title: "Reference"
description: "Lookup material for the Hem language and toolchain."
image: "https://hem.run/social/hem.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://hem.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

These reference pages document Hem language rules, syntax, and tooling. They are organized for quick lookup rather than step-by-step learning. If you are new to Hem, start with [the tour](/).

## Language

[Expressions and control flow](/reference/control-flow) covers expression-based `if`, `match`,
`try`, and `catch`, block return values, guarded bindings, loops, and cases where expressions are not
permitted as values.

[Data transformation](/reference/data-transformation) covers immutable variable bindings, variable
shadowing, destructuring, arrow functions, and first-argument pipe operators that compile to standard
function calls.

[Safety by construction](/reference/safety) details compiler checks that prevent truthiness
checks, type coercion in equality, mixed-type `+` operations, unchecked array indexing, implicit
mutation, unused Option/Result values, and untyped `any` leaks.

[Absence (`?T`)](/reference/absence) covers the unboxed representation of optional values
(`undefined`/`null`): how `?T` is created, how it is handled and unpacked, and where the underlying
JavaScript representation appears.

[Variants, brands, and errors](/reference/variants-and-brands) covers custom variant types, nominal
brand types, tagged errors, their emitted TypeScript types, and structural equality generation via
`deriving Eq`.

[Pattern matching](/reference/pattern-matching) covers pattern syntax, `as` variable bindings,
exhaustiveness checking for closed types, record pattern matching, and multi-value tuple matches.

[Errors and failures](/reference/typed-failures) covers `error` declarations, `raise`, postfix
`catch`, `try` blocks, error propagation, which failures appear in types, and how error handling
maps to Effect error channels.

[Concurrency and resources](/reference/concurrency-and-resources) covers concurrent `and` groups
across values, Promises, carriers, and Effects, as well as `use`, `resource`, `defer`, resource
ownership, task cancellation, and cleanup order.

[JSX](/reference/jsx) covers conditional rendering, pattern matching within JSX expressions, prop
shorthand syntax, optional props, explicit boolean attributes, and compilation to standard TSX.

[Standard Option and Result](/reference/standard-carriers) covers `@hem-lang/std` imports, boxed
Option and Result types, helper methods, `Some` / `Ok` carrier bindings, must-use validation, async
handling, Effect integration, and JavaScript interop.

[TypeScript interop](/reference/typescript-interop) covers TypeScript type checker integration,
imported types, type narrowing, type predicates, assertion functions, tagged templates,
directives, class declarations, JSX, and generated sibling files.

[Removed constructs](/reference/removed-typescript) lists unsupported JavaScript and TypeScript
features, their typed alternatives in Hem, operator restrictions, and must-use enforcement.

[Effect boundaries](/reference/effect-boundaries) covers the optional Effect extension, including
capability verification and compiler checks for bindings, execution boundaries, channel types, and
scoped resources.

## Toolchain

[The hem CLI](/reference/cli) documents CLI commands, options, file resolution rules, and output
files.

[Configuration](/reference/configuration) covers `tsconfig.json` settings, compiler type-checking
options, Vite plugin configuration, and generated file manifests.

[Diagnostics](/reference/diagnostics) lists all compiler diagnostic codes and explanations. This list
is generated directly from the compiler registry.

## Normative sources

The language specification and grammar define official language behavior:

- [Specification 0.2](https://github.com/ozanvos/hem/blob/main/hem-spec/hem-spec-0.2.md) defines language semantics.
- [Grammar 0.2](https://github.com/ozanvos/hem/blob/main/hem-spec/hem-grammar-0.2.md) defines syntax, operator precedence, and grammar rules.
- [Standard carriers 0.1](https://github.com/ozanvos/hem/blob/main/hem-spec/hem-standard-carriers-0.1.md) defines the Option and Result contract.

Reference pages cite relevant specification sections. If a reference page conflicts with the specification, the specification takes precedence.

Source: https://hem.run/reference/index.mdx