Comptime

Explicit Form

import { comptime } from "vibelang:comptime"
 
const value = comptime(expression)
const buildFunction = comptime(functionValue)

comptime(expression) requires the expression to evaluate during compilation. When the argument is a function, the call marks and returns a compile-time function; it does not invoke the function. Calling the returned function requires that call to evaluate during compilation.

For an immediately evaluated block:

const value = comptime(() => {
  // deterministic compile-time work
  return result
})()

The compiler recognizes the resolved import identity. Import aliases retain these semantics; unrelated functions named comptime do not. vibelang:comptime is a compiler-owned virtual module and has no ordinary uncompiled runtime fallback.

Valid result categories include:

• runtime-emittable values
• comptime-only values
• types
• typed module descriptions from loaders

Durable Plan IR is produced separately through durable(...), not by executing a Flow as a compile-time function.

Implicit Evaluation

The compiler may evaluate code automatically when all inputs are known. Implicit evaluation must not change observable runtime semantics.

Target

import { comptime } from "vibelang:comptime"
 
comptime.target

Current target vocabulary is direction and includes:

node  bun  deno  browser  edge  native  wasm

A branch resolved from comptime.target is eliminated for other targets.

Allowed Inputs

Comptime code may depend on:

• literals and other comptime values
• checked pure computation
• compiler configuration exposed through a typed API
• compiler-tracked imports and embedded assets
• loader-context dependencies

Unavailable Ambient State

Comptime code cannot directly observe:

filesystem  network  environment  process  clock  random  mutable host state

An equivalent input is valid only when supplied through a tracked compiler mechanism.

Loader Contract

A loader conceptually receives:

type Loader = (
  asset: CompilerAsset,
  context: LoaderContext,
) => TypedModule

The context records transitive imports and reports structured diagnostics. Exact declaration and registration syntax is open.

Cache Identity

A comptime result is keyed by all semantically relevant inputs, including:

compiler version
evaluated implementation graph
configuration
target
source bytes
transitive dependency hashes

Process-local function identity is insufficient for a portable cache key.

Errors

Compilation fails when explicit comptime(...) code:

• depends on a runtime-only value
• requests an unavailable capability
• exceeds resource limits
• produces an invalid type or module
• attempts an untracked read
• uses an operation unsupported by the target-neutral evaluator

Loader diagnostics should retain source spans into the original asset.