LazyImportOptions

LazyImportOptions = object

Defined in: src/util/LazyImport.ts:37

Import an optional peer dependency, or fail with an error that names the package and the command that installs it.

The framework’s brokers, caches and persistence backends all sit behind optional peers (mqtt, kafkajs, memjs, …), and a user-written integration is built the same way: the module must not be a hard dependency, so the import has to be dynamic, so the failure mode is a bare Cannot find module that says nothing about which package is missing or what to do about it. This helper owns that one boundary, so every site words it the same way.

Usage:

const mqttLazy = Lazy.of(() => lazyImportModule(‘mqtt’, { context: ‘MqttActor’ }));

When the peer-dep is missing, the user sees:

Error: MqttActor requires the ‘mqtt’ package. Install it with: npm install mqtt Original error: Cannot find module ‘mqtt’

Why this isn’t for every await import(...) site: built-in Node modules (node:dns, node:fs) never produce this error in practice; wrapping them adds noise without benefit. The helper is intended for actual peer-deps where “module not found” is the expected failure mode.

ESM default-export normalisation is intentionally NOT in this helper. Some peer-deps ship CJS (module.exports = value), others ESM (export default value), and some both — the right normalisation varies per module. Callers handle that explicitly at their site; this helper only owns the “import it OR throw a helpful error” boundary.

Properties

context?

readonly optional context?: string

Defined in: src/util/LazyImport.ts:44

User-facing context that gets prefixed to the error message. Typically the actor / extension that needs the module — gives the user a hint about WHICH part of their code triggered the import. Default: derived from the module name.

---

installHint?

readonly optional installHint?: string

Defined in: src/util/LazyImport.ts:49

Override the suggested install command in the error message. Default: npm install <name>.