List alternatives

Sometimes one value can have several valid forms. In other cases, a value must meet several requirements at once. Forst uses unions for alternatives and intersections for combined requirements. The supported union forms are named error unions and named homogeneous literal unions (string, integer, or boolean literals). Other general unions and intersections remain experimental.

List the possible string or numeric values of a field

Use a literal union when a field can contain only a specific set of primitive values. The | operator separates each literal value.

Forst
Generated Go
Generated TypeScript

type TaskStatus =
    | "todo"
    | "in_progress"
    | "success"
    | "failed"

// forst build
const (
	TaskStatus_todo        TaskStatus = "todo"
	TaskStatus_in_progress TaskStatus = "in_progress"
	TaskStatus_success     TaskStatus = "success"
	TaskStatus_failed      TaskStatus = "failed"
)

// TaskStatus: named literal union (4 members)
type TaskStatus string

func isTaskStatus(v string) bool {
	switch TaskStatus(v) {
	case TaskStatus_todo, TaskStatus_in_progress, TaskStatus_success, TaskStatus_failed:
		return true
	}
	return false
}

// forst generate → @forst/gen
export type TaskStatus = "todo" | "in_progress" | "success" | "failed";

Use ensure with the bare type name to validate untrusted input at runtime:

Forst
Generated Go

type TaskStatus =
    | "todo"
    | "in_progress"
    | "success"
    | "failed"

error BadStatus {}

func updateStatus(raw String) {
	ensure raw is TaskStatus else BadStatus{}
	// raw is narrowed to TaskStatus here
}

// forst build
const (
	TaskStatus_todo        TaskStatus = "todo"
	TaskStatus_in_progress TaskStatus = "in_progress"
	TaskStatus_success     TaskStatus = "success"
	TaskStatus_failed      TaskStatus = "failed"
)

type BadStatus struct{}

type TaskStatus string

func (e BadStatus) Error() string { return "error" }

func (e BadStatus) ForstErrorTag() string { return "main/BadStatus" }

func isTaskStatus(v string) bool {
	switch TaskStatus(v) {
	case TaskStatus_todo, TaskStatus_in_progress, TaskStatus_success, TaskStatus_failed:
		return true
	}
	return false
}

func updateStatus(raw string) error {
	if !isTaskStatus(raw) {
		return BadStatus{}
	}
	return nil
}

After ensure raw is TaskStatus, raw has the narrowed TaskStatus type. See Check a value.

Subset types

A smaller literal union is assignable to a larger literal union that contains all of its values.

Forst
Generated Go

type TaskStatus =
    | "todo"
    | "in_progress"
    | "success"
    | "failed"

type PendingStatus =
    | "todo"
    | "in_progress"

// forst build
const (
	PendingStatus_todo        PendingStatus = "todo"
	PendingStatus_in_progress PendingStatus = "in_progress"
)

const (
	TaskStatus_todo        TaskStatus = "todo"
	TaskStatus_in_progress TaskStatus = "in_progress"
	TaskStatus_success     TaskStatus = "success"
	TaskStatus_failed      TaskStatus = "failed"
)

type PendingStatus string
type TaskStatus string

func isPendingStatus(v string) bool {
	switch PendingStatus(v) {
	case PendingStatus_todo, PendingStatus_in_progress:
		return true
	}
	return false
}

func isTaskStatus(v string) bool {
	switch TaskStatus(v) {
	case TaskStatus_todo, TaskStatus_in_progress, TaskStatus_success, TaskStatus_failed:
		return true
	}
	return false
}

PendingStatus is assignable to TaskStatus because every value in PendingStatus belongs to TaskStatus. The reverse assignment (TaskStatus to PendingStatus) is rejected unless you validate the value first with ensure.

Exhaustive switches

When a switch statement handles a literal union, the compiler checks that every possible value is covered.

Forst
Generated Go

type TaskStatus =
    | "todo"
    | "in_progress"
    | "success"
    | "failed"

func handleStatus(s TaskStatus) {
	switch s {
	case "todo":
		// ...
	case "in_progress":
		// ...
	case "success":
		// ...
	case "failed":
		// ...
	}
}

// forst build — switch cases become typed constants
const (
	TaskStatus_todo        TaskStatus = "todo"
	TaskStatus_in_progress TaskStatus = "in_progress"
	TaskStatus_success     TaskStatus = "success"
	TaskStatus_failed      TaskStatus = "failed"
)

type TaskStatus string

func handleStatus(s TaskStatus) {
	switch s {
	case TaskStatus_todo:
	case TaskStatus_in_progress:
	case TaskStatus_success:
	case TaskStatus_failed:
	}
}

If a case is missing and there is no default clause, the compiler reports a non-exhaustive switch diagnostic. Unreachable default cases when all values are handled are also reported.

List the errors a function can return

Use an error union when a function has a small set of expected failures.

Forst
Generated Go

error ParseFailed {
	code: Int,
}

error IoFailed {
	path: String,
}

type LoadFailed = ParseFailed | IoFailed

func load(): Result(Int, LoadFailed) {
	return 0
}

// forst build
// LoadFailed is a closed union of nominal errors (only these types implement it).
type LoadFailed interface {
	isLoadFailed()
}

type IoFailed struct {
	path string
}

type ParseFailed struct {
	code int
}

func (e IoFailed) Error() string { return "error" }
func (e ParseFailed) Error() string { return "error" }

func (e IoFailed) ForstErrorTag() string { return "main/IoFailed" }
func (e ParseFailed) ForstErrorTag() string { return "main/ParseFailed" }

func (IoFailed) isLoadFailed() {}
func (ParseFailed) isLoadFailed() {}

func load() (int, error) {
	return 0, nil
}

LoadFailed accepts ParseFailed or IoFailed. Each error keeps its own fields. The Result tells callers that load returns an integer or one of these two failures. See Return a named error and Functions that can fail for how to create and return the errors.

Handle one error from the list

Use Err(ErrorName) when each error needs a different response.

Forst
Generated Go

error ParseFailed {
	code: Int,
}

error IoFailed {
	path: String,
}

type LoadFailed = ParseFailed | IoFailed

func load(): Result(Int, LoadFailed) {
	return 0
}

func handleParseFailed(err ParseFailed) {}

func inspect() {
	result := load()
	if result is Err(ParseFailed) {
		handleParseFailed(result)
	}
}

// forst build
type LoadFailed interface {
	isLoadFailed()
}

type IoFailed struct {
	path string
}

type ParseFailed struct {
	code int
}

func (e IoFailed) Error() string { return "error" }
func (e ParseFailed) Error() string { return "error" }

func (e IoFailed) ForstErrorTag() string { return "main/IoFailed" }
func (e ParseFailed) ForstErrorTag() string { return "main/ParseFailed" }

func (IoFailed) isLoadFailed() {}
func (ParseFailed) isLoadFailed() {}

func load() (int, error) {
	return 0, nil
}

func handleParseFailed(err ParseFailed) {}

func inspect() {
	result, resultErr := load()
	if func() bool {
		if resultErr == nil {
			return false
		}
		_, ok := resultErr.(ParseFailed)
		return ok
	}() {
		_ = result
		handleParseFailed(resultErr.(ParseFailed))
	}
}

Inside the branch, result is a ParseFailed. Generated Go uses an interface that only the listed errors implement. Generated TypeScript uses the same alternatives.

Accept several kinds of value

A general union can describe a value with several possible object or primitive types.

Forst
Generated Go

type Identifier = String | Int

// forst build
// Identifier: TypeDefBinaryExpr(TypeDefAssertionExpr(String) | TypeDefAssertionExpr(Int))
type Identifier any

Forst can parse and check this named declaration. Generated Go currently uses any for a general union, so type detail is lost after generation. Avoid general unions in application contracts until general Go output and narrowing are complete.

Require several sets of fields

An intersection uses &. It describes a value that must satisfy every member.

Forst
Generated Go

type Named = {
	name: String,
}

type Entity = {
	id: Int,
}

type NamedEntity = Named & Entity

// forst build
// type NamedEntity: intersection Named & Entity is empty (unrelated types)

NamedEntity requires both name and id. Intersection parsing and type checking exist, while complete narrowing and generated Go types remain in development. Treat intersections as experimental.

Choose the type for the job

Start from the behavior your function needs.

Need	Type
Limit a string, int, or bool field to known values	Named literal union (`"todo" \| "done"`)
Return a success value or a failure	`Result(Success, Failure)`
Limit a `Result` to known error types	A named error union
Keep several returned values together	`Tuple(T₁…Tₙ)`
Require all listed type rules	An intersection

Result and Tuple have different guarantees. See why they stay separate before wrapping calls with several return values.

Current limits

Literal unions must be homogeneous (all string, all integer, or all boolean literals). Mixed, float, inline, shape, tagged, and general disjunctive unions remain experimental or planned.
Union and intersection syntax works in named type declarations (type T = ...).
Inline forms such as a parameter typed directly as "a" | "b" are unavailable; declare a named type.
Named error unions and named homogeneous literal unions are the supported end-to-end union paths.
Arbitrary type unions (String | Int) lose detail in generated Go.
Optional types such as T | Nil are still planned.

See the roadmap for current implementation status.

Examples

See the tested error union and literal union examples on GitHub:

Continue with typed failures or runtime narrowing.

Return a named error

Return and handle named failures.

Check a value

Refine values after runtime checks.

Functions that can fail

Result returns and Ok / Err checks.

Overview

Getting started

Language

Interoperability

Workflow

List alternatives

List the possible string or numeric values of a field

Subset types

Exhaustive switches

List the errors a function can return

Handle one error from the list

Accept several kinds of value

Require several sets of fields

Choose the type for the job

Current limits

Examples

Return a named error

Check a value

Functions that can fail

​List the possible string or numeric values of a field

​Subset types

​Exhaustive switches

​List the errors a function can return

​Handle one error from the list

​Accept several kinds of value

​Require several sets of fields

​Choose the type for the job

​Current limits

​Examples

​Related

Return a named error

Check a value

Functions that can fail

List the possible string or numeric values of a field

Subset types

Exhaustive switches

List the errors a function can return

Handle one error from the list

Accept several kinds of value

Require several sets of fields

Choose the type for the job

Current limits

Examples

Related