Warning: VibeLang is v0. The language will change in major, breaking ways. It is not suitable for production use.

Control operations and handlers

A control operation lets a handler decide how the caller continues. Use one when a dependency must pause a program, answer a request, or end the program early.

Declare and perform an operation

VibeLang

// approval.vibe
// run: Console.log(handle(() => release("v1"), Approval, { approve: (_request, k) => resume(k, true) }))
export errorclass ReviewBusy ReviewBusyclass ReviewBusy { request(property) request: string: string }

export controlabstract class Approval Approvalabstract class Approval {
  approve(method) Approval.approve(request: string): boolean!ReviewBusy!(request(parameter) request: string: string): boolean!ReviewBusyclass ReviewBusy
}

export function releasefunction release(version: string): string!ReviewBusy!Approval(version(parameter) version: string: string) {
  if (!Approvalabstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.(`deploy ${version(parameter) version: string} to staging`)) return "staging declined"
  if (!Approvalabstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.(`deploy ${version(parameter) version: string} to production`)) return "production declined"
  return `released ${version(parameter) version: string}`
}
// string!ReviewBusy!Approval
// Output: released v1

Types in this example

error: class ReviewBusy
ReviewBusy: class ReviewBusy
request: (property) request: string
control: abstract class Approval
Approval: abstract class Approval
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!
request: (parameter) request: string
release: function release(version: string): string!ReviewBusy!Approval
version: (parameter) version: string
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.

Approval.approve returns a boolean at the call. Approval stays in the program's requirements until a handler answers it. Each abstract operation states all three channels of its contract.

Control, handle, resume, resumeWith, and abandon are globals in .vibe files.

Run one program with two policies

VibeLang

// policies.vibe
// run: Console.log(JSON.stringify(comparePolicies()))
import { Approval(alias) abstract class Approval, release(alias) function release(version: string): string!ReviewBusy!Approval } from "./approval.vibe"

export function autoApprovefunction autoApprove(version: string): string!ReviewBusy!(version(parameter) version: string: string) {
  try {
    return release(alias) function release(version: string): string!ReviewBusy!ApprovalRuns here and returns string.(version(parameter) version: string)
  } handle Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!(_requestconst _request: string) {
    resumeconst resume: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, value: boolean) => !!Runs here and returns never.Continues the program with value at the perform site; returns what the handle then produces.(true)
  }
}

export function scriptedReviewfunction scriptedReview(version: string, decisions: ReadonlyArray<boolean>): string!ReviewBusy!(version(parameter) version: string: string, decisions(parameter) decisions: readonly boolean[]: ReadonlyArrayinterface ReadonlyArray<T><boolean>) {
  let nextlet next: number = 0
  try {
    return release(alias) function release(version: string): string!ReviewBusy!ApprovalRuns here and returns string.(version(parameter) version: string)
  } handle Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!(_requestconst _request: string) {
    const approvedconst approved: boolean = decisions(parameter) decisions: readonly boolean[][nextlet next: number] ?? false
    nextlet next: number++
    resumeconst resume: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, value: boolean) => !!Runs here and returns never.Continues the program with value at the perform site; returns what the handle then produces.(approvedconst approved: boolean)
  }
}

export function comparePoliciesfunction comparePolicies(): string[]!ReviewBusy!() {
  return [autoApprovefunction autoApprove(version: string): string!ReviewBusy!Runs here and returns string.("v1"), scriptedReviewfunction scriptedReview(version: string, decisions: ReadonlyArray<boolean>): string!ReviewBusy!Runs here and returns string.("v1", [true, false])]
  // ["released v1", "production declined"]
}
// Output: ["released v1","production declined"]

Types in this example

Approval: (alias) abstract class Approval
release: (alias) function release(version: string): string!ReviewBusy!Approval
autoApprove: function autoApprove(version: string): string!ReviewBusy!
version: (parameter) version: string
release: (alias) function release(version: string): string!ReviewBusy!ApprovalRuns here and returns string.
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!
_request: const _request: string
resume: const resume: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, value: boolean) => !!Runs here and returns never.Continues the program with value at the perform site; returns what the handle then produces.
scriptedReview: function scriptedReview(version: string, decisions: ReadonlyArray<boolean>): string!ReviewBusy!
decisions: (parameter) decisions: readonly boolean[]
ReadonlyArray: interface ReadonlyArray<T>
next: let next: number
approved: const approved: boolean
comparePolicies: function comparePolicies(): string[]!ReviewBusy!
autoApprove: function autoApprove(version: string): string!ReviewBusy!Runs here and returns string.
scriptedReview: function scriptedReview(version: string, decisions: ReadonlyArray<boolean>): string!ReviewBusy!Runs here and returns string.

The business program stays the same. A handle clause after a try block names an operation, Approval.approve, and parameters that take the operation's parameter types. Each time the try block performs the operation, the clause runs.

resume(true) continues the try block with true as the operation's result. The handler is deep: the next approval request reaches the same clause. A clause that ends with resume runs in constant stack space, however many times the block performs the operation.

A return in the try block or in a clause returns from the enclosing function, and break and continue leave its loops. A statement answers every operation of each control it names: give each operation a clause (EK2108). One statement can handle several controls.

A clause can work after resume. The try block runs first, until it finishes. Then the clause goes on, and when the clause ends, the statement ends the way the try block did: a return in the try block takes effect after the clause, as a pending return waits for a finally block.

A continuation can be consumed once. Call resume, resumeWith, and abandon in the clause's own code, not in a function nested inside it. The runtime rejects a second resume.

Stop and clean up

VibeLang

// stopping.vibe
// run: Console.log(stopDeployment())
import { Approval(alias) abstract class Approval } from "./approval.vibe"

function deploymentfunction deployment(): string!ReviewBusy!Approval() {
  try {
    Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.("deploy to production")
    return "deployed"
  } finally {
    Console(alias) module "effect/Console".logconst log: (...args: ReadonlyArray<any>) => void!!Runs here and returns void.Logs a general-purpose message to the console.("deployment hold released")
  }
}

export function stopDeploymentfunction stopDeployment(): string!ReviewBusy!() {
  try {
    return deploymentfunction deployment(): string!ReviewBusy!ApprovalRuns here and returns string.()
  } handle Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!(_requestconst _request: string) {
    abandonconst abandon: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>) => void!!Runs here and returns void.Stops the program: its cleanup runs, its catch blocks do not. Fails if cleanup fails.()
    Console(alias) module "effect/Console".logconst log: (...args: ReadonlyArray<any>) => void!!Runs here and returns void.Logs a general-purpose message to the console.("cleanup finished")
    return "cancelled"
  }
}
// Output: deployment hold released
// Output: cleanup finished
// Output: cancelled

Types in this example

Approval: (alias) abstract class Approval
deployment: function deployment(): string!ReviewBusy!Approval
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.
Console: (alias) module "effect/Console"
log: const log: (...args: ReadonlyArray<any>) => void!!Runs here and returns void.Logs a general-purpose message to the console.
stopDeployment: function stopDeployment(): string!ReviewBusy!
deployment: function deployment(): string!ReviewBusy!ApprovalRuns here and returns string.
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!
_request: const _request: string
abandon: const abandon: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>) => void!!Runs here and returns void.Stops the program: its cleanup runs, its catch blocks do not. Fails if cleanup fails.

abandon() runs the try block's cleanup before the clause continues. It skips the block's catch blocks and runs its finally blocks and resource releases. Cleanup failures still fail the operation.

A clause that ends without resuming also stops the try block and cleans it up first. The statement then completes, and the function continues after it. Use abandon() when the clause needs cleanup to finish before its next statement.

Resume with an expected failure

VibeLang

// busy.vibe
// run: Console.log(busyReviewer())
import { Approval(alias) abstract class Approval, ReviewBusy(alias) class ReviewBusy } from "./approval.vibe"

export function busyReviewerfunction busyReviewer(): string!!() {
  try {
    return Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.("deploy now") ? "approved" : "declined"
  } handle Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!(requestconst request: string) {
    resumeWithconst resumeWith: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, program: boolean!NoInfer<ReviewBusy>!) => !!Runs here and returns never.Continues the program by running program at the perform site (D17): it
may fail only with the operation's declared errors, and needs nothing
(EK2005).(() => { throw new ReviewBusy(alias) constructor ReviewBusy<{
    readonly request: string;
}>(args: {
    readonly request: string;
}): ReviewBusy({ request(property) request: string }) })
  } catch (errorvar error: ReviewBusy) {
    return `review unavailable: ${errorvar error: ReviewBusy.request(property) request: string}`
  }
}
// Output: review unavailable: deploy now

Types in this example

Approval: (alias) abstract class Approval
ReviewBusy: (alias) class ReviewBusy
busyReviewer: function busyReviewer(): string!!
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!
request: const request: string
resumeWith: const resumeWith: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, program: boolean!NoInfer<ReviewBusy>!) => !!Runs here and returns never.Continues the program by running program at the perform site (D17): it may fail only with the operation's declared errors, and needs nothing (EK2005).
ReviewBusy: (alias) constructor ReviewBusy<{ readonly request: string; }>(args: { readonly request: string; }): ReviewBusy
request: (property) request: string
error: var error: ReviewBusy

resumeWith runs its program at the original operation call, inside the try block. This program can raise only errors declared by the operation, and it must need no services. Read services in the clause first, then capture their values in the program passed to resumeWith.

Catch clauses and a finally block may follow the handle clauses. They cover the try block and the clauses, so here the catch clause sees the ReviewBusy that the operation call raised.

Use handle as an expression

The statement is short for the handle function, which takes a program and returns its result:

VibeLang

// expression.vibe
// run: Console.log(countReleased(["v1", "v2"]))
import { Approval(alias) abstract class Approval, release(alias) function release(version: string): string!ReviewBusy!Approval } from "./approval.vibe"

export function countReleasedfunction countReleased(versions: ReadonlyArray<string>): number!ReviewBusy!(versions(parameter) versions: readonly string[]: ReadonlyArrayinterface ReadonlyArray<T><string>) {
  let releasedlet released: number = 0
  for (const versionconst version: string of versions(parameter) versions: readonly string[]) {
    const outcomeconst outcome: string = handlefunction handle<string, ReviewBusy, Approval, Approval, Approval, {
    approve(_request: string, k: Continuation<boolean, ReviewBusy, string>): string!!;
}>(program: string!ReviewBusy!Approval, control: Key<Approval, Approval>, clauses: {
    approve(_request: string, k: Continuation<boolean, ReviewBusy, string>): string!!;
}): ...!!Runs here and returns string.handle(program, Control, clauses, onReturn?): runs program with a deep
handler for Control's operations. Each clause receives the operation's
arguments and k, the rest of the program. The result is what the program
returns (through onReturn when given) or what a clause returns without
resuming. Inside a clause, resume(k, v) has the program's own result type;
with onReturn it has type never, so a clause's tail resume adds
nothing to the result (D97).(() => release(alias) function release(version: string): string!ReviewBusy!ApprovalRuns here and returns string.(versionconst version: string), Approval(alias) abstract class Approval, {
      approve(method) approve(_request: string, k: Continuation<boolean, ReviewBusy, string>): string!!(_request(parameter) _request: string, k(parameter) k: Continuation<boolean, ReviewBusy, string>) {
        return resumeconst resume: <boolean, ReviewBusy, string>(k: Continuation<boolean, ReviewBusy, string>, value: boolean) => string!!Runs here and returns string.Continues the program with value at the perform site; returns what the handle then produces.(k(parameter) k: Continuation<boolean, ReviewBusy, string>, true)
      }
    })
    if (outcomeconst outcome: string.startsWith(method) String.startsWith(searchString: string, position?: number): booleanReturns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.("released")) releasedlet released: number++
  }
  return releasedlet released: number
}
// Output: 2

Types in this example

Approval: (alias) abstract class Approval
release: (alias) function release(version: string): string!ReviewBusy!Approval
countReleased: function countReleased(versions: ReadonlyArray<string>): number!ReviewBusy!
versions: (parameter) versions: readonly string[]
ReadonlyArray: interface ReadonlyArray<T>
released: let released: number
version: const version: string
outcome: const outcome: string
handle: function handle<string, ReviewBusy, Approval, Approval, Approval, { approve(_request: string, k: Continuation<boolean, ReviewBusy, string>): string!!; }>(program: string!ReviewBusy!Approval, control: Key<Approval, Approval>, clauses: { approve(_request: string, k: Continuation<boolean, ReviewBusy, string>): string!!; }): ...!!Runs here and returns string.handle(program, Control, clauses, onReturn?): runs program with a deep handler for Control's operations. Each clause receives the operation's arguments and k, the rest of the program. The result is what the program returns (through onReturn when given) or what a clause returns without resuming. Inside a clause, resume(k, v) has the program's own result type; with onReturn it has type never, so a clause's tail resume adds nothing to the result (D97).
release: (alias) function release(version: string): string!ReviewBusy!ApprovalRuns here and returns string.
approve: (method) approve(_request: string, k: Continuation<boolean, ReviewBusy, string>): string!!
_request: (parameter) _request: string
k: (parameter) k: Continuation<boolean, ReviewBusy, string>
resume: const resume: <boolean, ReviewBusy, string>(k: Continuation<boolean, ReviewBusy, string>, value: boolean) => string!!Runs here and returns string.Continues the program with value at the perform site; returns what the handle then produces.
startsWith: (method) String.startsWith(searchString: string, position?: number): booleanReturns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at position. Otherwise returns false.

handle(program, Control, clauses, onReturn?) takes a program, the control class, and a clause for every operation. A clause receives the operation's arguments followed by k, the continuation, which resume(k, value), resumeWith(k, program), and abandon(k) take. resume returns the resumed program's result. The optional fourth argument of handle transforms normal returns. In this preview, resume is typed with the program's original result, or never when that fourth argument is supplied; avoid inspecting the resumed result when clauses return different types. Keep k inside its clause; never save it or return it.

Keep handlers on the executing fiber

VibeLang

// concurrent.vibe
// run: Console.log(JSON.stringify(approveAll(["staging", "production"])))
import { Approval(alias) abstract class Approval } from "./approval.vibe"

export function approveAllfunction approveAll(requests: ReadonlyArray<string>): boolean[]!ReviewBusy!(requests(parameter) requests: readonly string[]: ReadonlyArrayinterface ReadonlyArray<T><string>) {
  return forEachconst forEach: <boolean, ReviewBusy, never, readonly string[], false>(self: readonly string[], f: (a: string, i: number) => boolean!ReviewBusy!, options?: {
    readonly concurrency?: Concurrency | undefined;
    readonly discard?: false | undefined;
} | undefined) => boolean[]!ReviewBusy!Runs here and returns boolean[].Executes an effectful operation for each element in an Iterable.(requests(parameter) requests: readonly string[], (request(parameter) request: string) => {
    try {
      return Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.(request(parameter) request: string)
    } handle Approval(alias) abstract class Approval.approve(method) Approval.approve(request: string): boolean!ReviewBusy!(_requestconst _request: string) {
      resumeconst resume: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, value: boolean) => !!Runs here and returns never.Continues the program with value at the perform site; returns what the handle then produces.(true)
    }
  }, { concurrency(property) concurrency?: Concurrency | undefined: 4 })
}
// Output: [true,true]

Types in this example

Approval: (alias) abstract class Approval
approveAll: function approveAll(requests: ReadonlyArray<string>): boolean[]!ReviewBusy!
requests: (parameter) requests: readonly string[]
ReadonlyArray: interface ReadonlyArray<T>
forEach: const forEach: <boolean, ReviewBusy, never, readonly string[], false>(self: readonly string[], f: (a: string, i: number) => boolean!ReviewBusy!, options?: { readonly concurrency?: Concurrency | undefined; readonly discard?: false | undefined; } | undefined) => boolean[]!ReviewBusy!Runs here and returns boolean[].Executes an effectful operation for each element in an Iterable.
request: (parameter) request: string
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!Runs here and returns boolean.
approve: (method) Approval.approve(request: string): boolean!ReviewBusy!
_request: const _request: string
resume: const resume: <boolean, ReviewBusy, never>(k: Continuation<boolean, ReviewBusy, never>, value: boolean) => !!Runs here and returns never.Continues the program with value at the perform site; returns what the handle then produces.
concurrency: (property) concurrency?: Concurrency | undefined

Handle the operation inside each concurrent branch. A handler on the parent fiber cannot answer a child fiber's control operations.

Diagnostic	Meaning	Fix
EK2005	A `resumeWith` program needs a service or raises an undeclared error	Read the service in the clause; raise only the operation's declared errors
EK2107	A handle clause names an operation of something that is not a control, such as a service	Provide a service with a layer or a `provide` block
EK2108	A handle statement leaves an operation of its control without a clause, or gives one two clauses	Add the missing clause, or remove the second
EK4201	Work sent to another fiber still requires a control operation	Handle it inside the branch, or use sequential execution where the combinator supports it
EK4202	A TypeScript function's declared requirements include a control operation	Write it in VibeLang or handle the operation inside the TypeScript implementation

Stream operators run a producer on its own fiber too. Handle any control requirements inside the producer before passing it to a Stream operator. See Producers.