Results and Errors

Reference for expected failure values

Types

Result<A, E extends Error>
Promise<Result<A, E>>

A is the success type and E is the union of expected errors. Async fallible functions wrap the whole Result in an ordinary Promise.

Error Declaration

class HttpError extends Error {
  constructor(
    readonly status: number,
    readonly url: string,
  ) {
    super(`HTTP ${status}: ${url}`)
  }
}

No special error declaration or tagged-error base is used. The compiler attaches stable nominal identity and transport metadata to ordinary Error subclasses.

Function Authoring

function operation(): Result<Output, ErrorA | ErrorB> {
  if (conditionA) throw new ErrorA()
  if (conditionB) return otherOperation()
  return new Output()
}

Within a Result-returning function:

return value creates the success variant.
throw error creates the error variant.
returning a compatible Result forwards it without nesting.
result.unwrap() produces the success value or propagates its error.

There is no failure annotation, prefix propagation expression, postfix catch expression, or public Result.ok/Result.err constructor.

Result Methods

Method	Meaning
`isOk()`, `isError()`	inspect and narrow the variant
`match({ ok, error })`	exhaustively produce a value from either variant
`map`, `mapError`	transform one side
`andThen`	sequence success-dependent work
`recover`	replace an error with a value or Result
`tap`, `tapError`	observe without changing the Result
`unwrap`	compiler propagation point; throws in JS fallback
`unwrapOr`, `expect`	extract with fallback or invariant message
`Result.all`	collect Results, returning the first error
`Result.try`, `Result.tryPromise`	adapt a foreign throwing/rejecting operation

Results are must-use.

Error Methods

All Errors expose:

error.is(NotFound)
error.matches(NotFound, Timeout)
error.match({ NotFound: onMissing, Timeout: onTimeout })
error.matchPartial({ NotFound: onMissing }, onOther)
error.rootCause()

The compiler checks match exhaustiveness against the known E union and narrows each handler. Runtime dispatch uses stable nominal identity. matchPartial accepts an explicit fallback. rootCause follows standard Error.cause links.

Async

async function load(): Promise<Result<Output, Timeout>> {
  const response = (await request()).unwrap()
  return response.decode().unwrap()
}

await unwraps the Promise and leaves the Result. Promise instance .then(), .catch(), and .finally() are compile errors in authored VibeLang.

Foreign Exceptions and Defects

Result.try and Result.tryPromise convert unknown foreign throws or rejections to UnhandledException, or accept a mapper that returns a declared Error subtype. Reflect.panic(...) represents an unrecoverable invariant violation and bypasses Result recovery. Statement-form JavaScript try/catch is retained only for interop and observes normal JavaScript exceptions.

Transport

Worker and durable boundaries serialize a declared Error's stable identity, fields, message, cause, and codec version. Unknown foreign exceptions use the boundary's UnhandledException representation.

Suggest changes to this page