JSPrismarine

API reference / @jsprismarine/kernel / Kernel

Class: Kernel<Events> ​

Defined in: packages/kernel/src/kernel.ts:51

The module kernel. It owns lifecycle, a token-keyed service registry, and the event bus; everything else — worlds, sessions, commands, networking, the tick loop — is a module.

Lifecycle: construct the kernel once, register() modules, then drive it through registerAll(), start(), and stop(). registerAll() runs every module's register() phase exactly once and validates providers and the dependency graph; after it, get() resolves provided services. start() runs registerAll() first when it has not run, then runs the start() phases in dependency order. stop() runs stop() phases in reverse order, logging failures instead of throwing, and returns the kernel to the registered state, so the same kernel — and the services its modules constructed — can be started again. Event listeners a module attaches are detached when it stops; a module that must survive a restart attaches its listeners in start(), not register().

Type Parameters ​

Events ​

Events extends EventMap = EventMap

Constructors ​

Constructor ​

new Kernel<Events>(options?): Kernel<Events>

Defined in: packages/kernel/src/kernel.ts:66

Parameters ​

options? ​

KernelOptions = {}

Returns ​

Kernel<Events>

Accessors ​

events ​

Get Signature ​

get events(): EventBus<Events>

Defined in: packages/kernel/src/kernel.ts:72

The kernel-owned event bus, unscoped. Module code should use its context's scoped handle.

Returns ​

EventBus<Events>

Methods ​

get() ​

get<T>(token): T

Defined in: packages/kernel/src/kernel.ts:203

Resolves a service for the host or for tests. Module code should resolve through its context instead.

Type Parameters ​

T ​

T

Parameters ​

token ​

ServiceToken<T>

Returns ​

T

Throws ​

KernelError when no module has provided the token.

register() ​

register<Config>(module): void

Defined in: packages/kernel/src/kernel.ts:82

Adds a module. Legal only before registerAll() (or the first start(), which runs it).

Type Parameters ​

Config ​

Config

Parameters ​

module ​

Module<Config, Events>

Returns ​

void

Throws ​

KernelError after registerAll() or when a module with the same id is already registered.

registerAll() ​

registerAll(): Promise<void>

Defined in: packages/kernel/src/kernel.ts:106

Runs all register() phases, validates providers and the dependency graph, and computes the start order. After it resolves, get() resolves every provided service even though start() has not run. Runs at most once per kernel; later calls are no-ops.

Returns ​

Promise<void>

Throws ​

KernelError when a declared dependency has no provider or the dependency graph has a cycle.

start() ​

start(): Promise<void>

Defined in: packages/kernel/src/kernel.ts:140

Runs registerAll() when it has not run, then runs start() phases in dependency order. Legal again after stop(): the register() phases do not rerun, so the modules' services carry over into the next start.

A module whose start() throws leaves nothing running: the modules that had already started are stopped in reverse order, the kernel goes back to registered, and the error is rethrown. The failing module itself is not stopped, because its start never finished.

A stop() while this is still running wins: no further module starts, and this rejects with a KernelError once the module it was waiting on returns.

Returns ​

Promise<void>

Throws ​

KernelError when the kernel is already starting or started, when a declared dependency has no provider, or when the dependency graph has a cycle.

Throws ​

Whatever a module's start() throws, after the rollback.

stop() ​

stop(): Promise<void>

Defined in: packages/kernel/src/kernel.ts:175

Runs stop() phases in reverse start order and detaches each module's event listeners. Failures are logged, not thrown, so one module cannot block the others' teardown. Leaves the kernel registered, so start() may run it again.

Called while start() is still running, it stops the modules started so far and the one still starting, which is how a long start such as a world preload is cancelled. A no-op when nothing has started.

Returns ​

Promise<void>