Interface: ExtensionContext

Makaio Framework

---

Makaio Framework / contracts / ExtensionContext

Interface: ExtensionContext

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:13

Generic context provided by a host runtime when creating an extension’s service.

Contains host-agnostic runtime seams: the bus instance, extension identity, extension-local data directory, machine identity, config, service lookup, and lifecycle controls. Host-specific environment details belong on explicit context extensions such as NodeExtensionContext.

Extended by

• NodeExtensionContext

Properties

bus

readonly bus: IMakaioBus

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:15

Bus instance for registering handlers and emitting events.

---

config?

readonly optional config?: unknown

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:42

Resolved configuration for this extension, merged from stored values and descriptor defaults. Present only when the extension declared a configSchema on its MakaioExtension.

Extensions should parse this with their Zod schema to get typed config:

const config = parseExtensionConfig(MyConfigSchema, ctx.config);

---

dataDir

readonly dataDir: string

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:23

Per-extension writable data directory resolved by the host runtime.

Use this for extension-local persistence (caches, state files, etc.).

---

hasExtension

readonly hasExtension: (name) => boolean

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:75

Check whether an extension with the given name is active.

Returns true when the named extension has been loaded and reached active state. Use this for optional integration checks without requiring an ExtensionToken.

Parameters

name

string

Extension name to check.

Returns

boolean

true when the extension is active.

---

identity

readonly identity: ExtensionIdentity

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:17

Coordinator-minted identity for the extension being created.

---

machineId

readonly machineId: string

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:31

Stable machine identifier used for machine-scoped persistence and encryption key derivation.

Resolved by the composition root (e.g., node-machine-id) before extensions are started.

---

signal

readonly signal: AbortSignal

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:65

Abort signal triggered during graceful shutdown.

Extensions can pass this to long-running operations (fetch, timers, streams) so they cancel promptly when the runtime is stopping.

---

tryImport

readonly tryImport: <T>(specifier) => Promise<T | null>

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:58

Attempt a dynamic import, returning null when the package is not installed.

Only swallows errors caused by the package itself being absent. Transitive dependency failures and module evaluation errors are re-thrown.

Type Parameters

T

T

Expected module shape (caller-asserted, not runtime-verified).

Parameters

specifier

string

Package specifier to import.

Returns

Promise<T | null>

The imported module cast to T, or null when the package is not installed.

Methods

getService()

getService<T>(token): T | undefined

Defined in: ../../../packages/contracts/src/extension/extension-context.ts:48

Retrieve a service exposed by another active extension.

Type Parameters

T

T

Parameters

token

ExtensionToken<T>

Extension-owned token identifying the desired service.

Returns

T | undefined

The active service instance, or undefined when unavailable.