interface IRuntimeServices
Since 0.1.0

Runtime services — every runtime-specific operation the framework needs, abstracted behind one interface. Registered under CAPABILITIES.RUNTIME by the RuntimePlugin, which is mandatory in every application.

Examples

Example 1

const runtime = ctx.services.get<IRuntimeServices>(CAPABILITIES.RUNTIME);
const requestId = runtime.uuid();

Properties

Web Crypto SubtleCrypto for cryptographic operations.

readonly
env: Readonly<Record<string, string | undefined>>

Environment variables. Always read env through this, never process.env.

Treat it as a snapshot taken when the runtime services were created: the Deno adapter materializes Deno.env.toObject() and the Workers adapter receives a per-invocation bindings object, so neither reflects a variable set after startup. (The Node and Bun adapters pass process.env through, which does.) Nothing in the framework mutates the environment at runtime.

readonly
optional
fs: IFileSystem

File system access; absent on runtimes without one (edge platforms).

readonly
optional
workers: IWorkerHost

Worker-thread spawning; absent on runtimes without threads (edge platforms).

Since 0.2.0
readonly
optional
dns: IDnsResolver

DNS resolution; absent on runtimes with no resolver API (edge platforms).

Cloudflare Workers omits this key entirely — its network access is fetch, which resolves names internally and exposes no lookup surface.

Methods

Identifies the current runtime.

version(): string

Returns the runtime version string.

hostname(): string

Returns the host name, when the runtime exposes one.

uuid(): string

Generates a UUID v4.

randomBytes(length: number): Uint8Array

Generates cryptographically secure random bytes.

now(): number

Returns the current wall-clock time in milliseconds since the epoch.

hrtime(): number

Returns a high-resolution monotonic timestamp in milliseconds, suitable for measuring durations.

setTimeout(
fn: () => void,
ms: number
): TimerHandle

Schedules a one-shot callback.

clearTimeout(handle: TimerHandle): void

Cancels a setTimeout.

setInterval(
fn: () => void,
ms: number
): TimerHandle

Schedules a repeating callback.

clearInterval(handle: TimerHandle): void

Cancels a setInterval.

exit(code?: number): never

Terminates the process.

Since 0.3.0
optional
onSignal(
signal: RuntimeSignal,
handler: () => void
): void

Registers a handler for a process-termination signal, so an application can run app.stop() before the process dies.

Without this, an application catching SIGTERM has to reach for Deno.addSignalListener or process.on directly — a runtime API in application code, which is what AI_GUIDELINES §4.2 exists to prevent, and which forces a different entry point per target.

Absent on two platforms, for two different reasons. Cloudflare Workers omits the key entirely: an isolate is evicted, never signalled, so there is nothing to register for. The Deno adapter omits it on Windows, where Deno.addSignalListener('SIGTERM') throws — so a caller must treat this as optional (runtime.onSignal?.(…)) rather than assuming a non-edge runtime always provides it.

Handlers are additive: registering twice for one signal runs both, in registration order. The framework never removes them — a process that has received a termination signal is ending.

Usage

import { type IRuntimeServices } from "common/src/index.ts";