actor-ts 0.9.0

package/dist/util/Either.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Either<L, R> — a value that is either `Left<L>` (by convention: the
+ * error / alternative) or `Right<R>` (by convention: the success /
+ * primary value).  Mirrors Scala's `scala.util.Either`.
+ *
+ * Why pick `Either` over `Try`?
+ *   - `Try` is fixed to thrown `Error`s on the failure side.  `Either`
+ *     lets the failure type be anything — a typed error enum, a
+ *     validation-message list, a pair of {code, reason}.
+ *   - `Either` is "right-biased" by default: `map` / `flatMap` operate
+ *     on the Right side and let Left pass through, matching the Scala
+ *     2.12+ convention.
+ *
+ * Why pick `Either` over `Option`?
+ *   - `Option` discards WHY a value was absent.  `Either` keeps it.
+ *
+ * Usage:
+ *   type ParseError = { line: number; msg: string };
+ *
+ *   function parseConfig(src: string): Either<ParseError, Config> {
+ *     try { return Either.right(JSON.parse(src) as Config); }
+ *     catch (e) { return Either.left({ line: 0, msg: (e as Error).message }); }
+ *   }
+ *
+ *   parseConfig(raw)
+ *     .map(c => c.port)
+ *     .fold(
+ *       err => log.error(`bad config on line ${err.line}: ${err.msg}`),
+ *       port => listen(port),
+ *     );
+ */
+/** The Left branch — by convention the error / alternative. */
+export declare class Left<L> {
+    readonly value: L;
+    readonly _tag: "Left";
+    constructor(value: L);
+    isLeft(): this is Left<L>;
+    isRight(): this is Right<never>;
+    /** Right-biased `map` — Left passes through. */
+    map<U>(_f: (r: never) => U): Either<L, U>;
+    /** Right-biased `flatMap` — Left passes through. */
+    flatMap<R2>(_f: (r: never) => Either<L, R2>): Either<L, R2>;
+    /** Map the Left side. */
+    mapLeft<U>(f: (l: L) => U): Either<U, never>;
+    /** Map BOTH sides. */
+    bimap<U, V>(onLeft: (l: L) => U, _onRight: (r: never) => V): Either<U, V>;
+    /** Collapse to a single value. */
+    fold<T>(onLeft: (l: L) => T, _onRight: (r: never) => T): T;
+    /** Swap the sides. */
+    swap(): Either<never, L>;
+    /** Left → fallback. */
+    getOrElse<U>(fallback: U | ((l: L) => U)): U;
+    /** Left → alternative; Right → self. */
+    orElse<R2>(alt: Either<L, R2> | (() => Either<L, R2>)): Either<L, R2>;
+    /** Side-effect runs on Right; no-op on Left. */
+    forEach(_f: (r: never) => void): void;
+    /** Optional conversion — Left → null. */
+    toNullable(): null;
+}
+/** The Right branch — by convention the primary value. */
+export declare class Right<R> {
+    readonly value: R;
+    readonly _tag: "Right";
+    constructor(value: R);
+    isLeft(): this is Left<never>;
+    isRight(): this is Right<R>;
+    /** Right-biased `map` — transform the inner value. */
+    map<U>(f: (r: R) => U): Either<never, U>;
+    /** Right-biased `flatMap`. */
+    flatMap<L2, R2>(f: (r: R) => Either<L2, R2>): Either<L2, R2>;
+    /** Right passes through `mapLeft` untouched. */
+    mapLeft<U>(_f: (l: never) => U): Either<U, R>;
+    /** Map BOTH sides. */
+    bimap<U, V>(_onLeft: (l: never) => U, onRight: (r: R) => V): Either<U, V>;
+    /** Collapse to a single value. */
+    fold<T>(_onLeft: (l: never) => T, onRight: (r: R) => T): T;
+    /** Swap the sides. */
+    swap(): Either<R, never>;
+    /** Right → the value; fallback ignored. */
+    getOrElse<U>(_fallback: U | ((l: never) => U)): R;
+    /** Right → self; alternative ignored. */
+    orElse<R2>(_alt: Either<never, R2> | (() => Either<never, R2>)): Either<never, R>;
+    /** Side-effect on the Right value. */
+    forEach(f: (r: R) => void): void;
+    /** Optional conversion — Right → the value. */
+    toNullable(): R;
+}
+export type Either<L, R> = Left<L> | Right<R>;
+/** Factory for Left. */
+export declare function left<L>(value: L): Left<L>;
+/** Factory for Right. */
+export declare function right<R>(value: R): Right<R>;
+/** Collect Right values; short-circuit to the first Left encountered. */
+export declare function eitherSequence<L, R>(values: ReadonlyArray<Either<L, R>>): Either<L, R[]>;
+/**
+ * Convert a thunk into `Either<Error, R>` — Right on return, Left with
+ * the thrown value (coerced to Error) on throw.
+ */
+export declare function eitherOf<R>(compute: () => R): Either<Error, R>;
+//# sourceMappingURL=Either.d.ts.map

package/dist/util/Either.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Either.d.ts","sourceRoot":"","sources":["../../src/util/Either.ts"],"names":[],"mappings":"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"}

package/dist/util/Either.js

@@ -0,0 +1,128 @@
+/**
+ * Either<L, R> — a value that is either `Left<L>` (by convention: the
+ * error / alternative) or `Right<R>` (by convention: the success /
+ * primary value).  Mirrors Scala's `scala.util.Either`.
+ *
+ * Why pick `Either` over `Try`?
+ *   - `Try` is fixed to thrown `Error`s on the failure side.  `Either`
+ *     lets the failure type be anything — a typed error enum, a
+ *     validation-message list, a pair of {code, reason}.
+ *   - `Either` is "right-biased" by default: `map` / `flatMap` operate
+ *     on the Right side and let Left pass through, matching the Scala
+ *     2.12+ convention.
+ *
+ * Why pick `Either` over `Option`?
+ *   - `Option` discards WHY a value was absent.  `Either` keeps it.
+ *
+ * Usage:
+ *   type ParseError = { line: number; msg: string };
+ *
+ *   function parseConfig(src: string): Either<ParseError, Config> {
+ *     try { return Either.right(JSON.parse(src) as Config); }
+ *     catch (e) { return Either.left({ line: 0, msg: (e as Error).message }); }
+ *   }
+ *
+ *   parseConfig(raw)
+ *     .map(c => c.port)
+ *     .fold(
+ *       err => log.error(`bad config on line ${err.line}: ${err.msg}`),
+ *       port => listen(port),
+ *     );
+ */
+/** The Left branch — by convention the error / alternative. */
+export class Left {
+    value;
+    _tag = 'Left';
+    constructor(value) {
+        this.value = value;
+    }
+    isLeft() { return true; }
+    isRight() { return false; }
+    /** Right-biased `map` — Left passes through. */
+    map(_f) { return this; }
+    /** Right-biased `flatMap` — Left passes through. */
+    flatMap(_f) { return this; }
+    /** Map the Left side. */
+    mapLeft(f) { return new Left(f(this.value)); }
+    /** Map BOTH sides. */
+    bimap(onLeft, _onRight) {
+        return new Left(onLeft(this.value));
+    }
+    /** Collapse to a single value. */
+    fold(onLeft, _onRight) { return onLeft(this.value); }
+    /** Swap the sides. */
+    swap() { return new Right(this.value); }
+    /** Left → fallback. */
+    getOrElse(fallback) {
+        return typeof fallback === 'function'
+            ? fallback(this.value)
+            : fallback;
+    }
+    /** Left → alternative; Right → self. */
+    orElse(alt) {
+        return typeof alt === 'function' ? alt() : alt;
+    }
+    /** Side-effect runs on Right; no-op on Left. */
+    forEach(_f) { }
+    /** Optional conversion — Left → null. */
+    toNullable() { return null; }
+}
+/** The Right branch — by convention the primary value. */
+export class Right {
+    value;
+    _tag = 'Right';
+    constructor(value) {
+        this.value = value;
+    }
+    isLeft() { return false; }
+    isRight() { return true; }
+    /** Right-biased `map` — transform the inner value. */
+    map(f) { return new Right(f(this.value)); }
+    /** Right-biased `flatMap`. */
+    flatMap(f) { return f(this.value); }
+    /** Right passes through `mapLeft` untouched. */
+    mapLeft(_f) { return this; }
+    /** Map BOTH sides. */
+    bimap(_onLeft, onRight) {
+        return new Right(onRight(this.value));
+    }
+    /** Collapse to a single value. */
+    fold(_onLeft, onRight) { return onRight(this.value); }
+    /** Swap the sides. */
+    swap() { return new Left(this.value); }
+    /** Right → the value; fallback ignored. */
+    getOrElse(_fallback) { return this.value; }
+    /** Right → self; alternative ignored. */
+    orElse(_alt) { return this; }
+    /** Side-effect on the Right value. */
+    forEach(f) { f(this.value); }
+    /** Optional conversion — Right → the value. */
+    toNullable() { return this.value; }
+}
+/** Factory for Left. */
+export function left(value) { return new Left(value); }
+/** Factory for Right. */
+export function right(value) { return new Right(value); }
+/** Collect Right values; short-circuit to the first Left encountered. */
+export function eitherSequence(values) {
+    const out = [];
+    for (const e of values) {
+        if (e.isLeft())
+            return e;
+        out.push(e.value);
+    }
+    return new Right(out);
+}
+/**
+ * Convert a thunk into `Either<Error, R>` — Right on return, Left with
+ * the thrown value (coerced to Error) on throw.
+ */
+export function eitherOf(compute) {
+    try {
+        return new Right(compute());
+    }
+    catch (e) {
+        return new Left(e instanceof Error ? e : new Error(String(e)));
+    }
+}
+//# sourceMappingURL=Either.js.map

package/dist/util/Either.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Either.js","sourceRoot":"","sources":["../../src/util/Either.ts"],"names":[],"mappings":"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"}

package/dist/util/Lazy.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Lazy<T> — a value computed on first access, then memoised.  Mirrors
+ * Scala's `lazy val` and Kotlin's `lazy { }` — the thunk you pass in
+ * runs at most once; every subsequent `.get()` returns the cached
+ * result.  A thrown thunk caches the failure and re-throws on every
+ * subsequent access, matching the Scala semantics.
+ *
+ * Usage — plain memoised compute:
+ *   const config = Lazy.of(() => loadHoconFromEnv());
+ *   config.get();   // reads + parses once
+ *   config.get();   // same reference, zero work
+ *
+ * Usage — test reset:
+ *   const driver = Lazy.of(() => pickDriverForRuntime());
+ *   driver.reset();            // forget cached value
+ *   driver.setOverride(mock);  // force a specific value (test hook)
+ *
+ * Usage — mapping:
+ *   const port = Lazy.of(() => parseInt(process.env.PORT ?? '0', 10));
+ *   const url  = port.map((p) => `http://localhost:${p}`);
+ *   // `url.get()` evaluates `port.get()` on demand, then formats.
+ *
+ * For values whose computation is async, wrap the `Promise` — `Lazy.of
+ * (async () => …)` caches the Promise itself, so concurrent callers all
+ * await the same in-flight work (no duplicate initialisation).
+ */
+export declare class Lazy<T> {
+    private readonly compute;
+    private state;
+    private overrideValue;
+    private constructor();
+    /** Build a lazy cell from a thunk.  Preferred entry point. */
+    static of<T>(compute: () => T): Lazy<T>;
+    /** Build a lazy cell that's already evaluated to `value` (no thunk runs). */
+    static evaluated<T>(value: T): Lazy<T>;
+    /**
+     * Get the memoised value.  Runs the thunk on first call; subsequent
+     * calls return the cached result.  If the thunk threw, the same error
+     * is re-thrown on every subsequent access.
+     */
+    get(): T;
+    /**
+     * `true` once `.get()` can return without running the thunk — either
+     * the thunk has already been executed (success or failure both count),
+     * or an override is active.  `false` only in the initial pending
+     * state.
+     */
+    get isEvaluated(): boolean;
+    /** Return the cached value if already evaluated, else `undefined`. */
+    peek(): T | undefined;
+    /**
+     * Derive a new `Lazy` whose value is `f(this.get())`.  The derivation
+     * is itself lazy — `map(f)` does not force the source.
+     */
+    map<U>(f: (value: T) => U): Lazy<U>;
+    /**
+     * Derive a new `Lazy` whose value flattens a `Lazy<Lazy<U>>`.  Same
+     * laziness contract as `map`.
+     */
+    flatMap<U>(f: (value: T) => Lazy<U>): Lazy<U>;
+    /**
+     * Run a side effect against the evaluated value.  Forces evaluation;
+     * idempotent by virtue of the cache.
+     */
+    forEach(f: (value: T) => void): void;
+    /**
+     * Forget the memoised value so the next `get()` re-runs the thunk.
+     * Primarily a test hook — also clears any override set via
+     * `setOverride`.  In hot production paths, prefer building a new
+     * `Lazy` rather than resetting.
+     */
+    reset(): void;
+    /**
+     * Test hook: force `.get()` to return `value` without touching the
+     * thunk or the cache.  Call `reset()` (or `setOverride(null)`) to
+     * restore normal evaluation.
+     */
+    setOverride(value: T | null): void;
+}
+/** Shorthand alias matching Scala's `lazy val`. */
+export declare const lazy: typeof Lazy.of;
+//# sourceMappingURL=Lazy.d.ts.map

package/dist/util/Lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lazy.d.ts","sourceRoot":"","sources":["../../src/util/Lazy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,qBAAa,IAAI,CAAC,CAAC;IAIG,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH5C,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,aAAa,CAA6B;IAElD,OAAO;IAEP,8DAA8D;IAC9D,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAEvC,6EAA6E;IAC7E,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAMtC;;;;OAIG;IACH,GAAG,IAAI,CAAC;IAcR;;;;;OAKG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,sEAAsE;IACtE,IAAI,IAAI,CAAC,GAAG,SAAS;IAKrB;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAInC;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAI7C;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI;IAEpC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;CAGnC;AAED,mDAAmD;AACnD,eAAO,MAAM,IAAI,gBAAU,CAAC"}

package/dist/util/Lazy.js

@@ -0,0 +1,119 @@
+/**
+ * Lazy<T> — a value computed on first access, then memoised.  Mirrors
+ * Scala's `lazy val` and Kotlin's `lazy { }` — the thunk you pass in
+ * runs at most once; every subsequent `.get()` returns the cached
+ * result.  A thrown thunk caches the failure and re-throws on every
+ * subsequent access, matching the Scala semantics.
+ *
+ * Usage — plain memoised compute:
+ *   const config = Lazy.of(() => loadHoconFromEnv());
+ *   config.get();   // reads + parses once
+ *   config.get();   // same reference, zero work
+ *
+ * Usage — test reset:
+ *   const driver = Lazy.of(() => pickDriverForRuntime());
+ *   driver.reset();            // forget cached value
+ *   driver.setOverride(mock);  // force a specific value (test hook)
+ *
+ * Usage — mapping:
+ *   const port = Lazy.of(() => parseInt(process.env.PORT ?? '0', 10));
+ *   const url  = port.map((p) => `http://localhost:${p}`);
+ *   // `url.get()` evaluates `port.get()` on demand, then formats.
+ *
+ * For values whose computation is async, wrap the `Promise` — `Lazy.of
+ * (async () => …)` caches the Promise itself, so concurrent callers all
+ * await the same in-flight work (no duplicate initialisation).
+ */
+export class Lazy {
+    compute;
+    state = { kind: 'pending' };
+    overrideValue = null;
+    constructor(compute) {
+        this.compute = compute;
+    }
+    /** Build a lazy cell from a thunk.  Preferred entry point. */
+    static of(compute) { return new Lazy(compute); }
+    /** Build a lazy cell that's already evaluated to `value` (no thunk runs). */
+    static evaluated(value) {
+        const cell = new Lazy(() => value);
+        cell.state = { kind: 'value', value };
+        return cell;
+    }
+    /**
+     * Get the memoised value.  Runs the thunk on first call; subsequent
+     * calls return the cached result.  If the thunk threw, the same error
+     * is re-thrown on every subsequent access.
+     */
+    get() {
+        if (this.overrideValue !== null)
+            return this.overrideValue.value;
+        if (this.state.kind === 'value')
+            return this.state.value;
+        if (this.state.kind === 'error')
+            throw this.state.error;
+        try {
+            const value = this.compute();
+            this.state = { kind: 'value', value };
+            return value;
+        }
+        catch (e) {
+            this.state = { kind: 'error', error: e };
+            throw e;
+        }
+    }
+    /**
+     * `true` once `.get()` can return without running the thunk — either
+     * the thunk has already been executed (success or failure both count),
+     * or an override is active.  `false` only in the initial pending
+     * state.
+     */
+    get isEvaluated() {
+        return this.overrideValue !== null || this.state.kind !== 'pending';
+    }
+    /** Return the cached value if already evaluated, else `undefined`. */
+    peek() {
+        if (this.overrideValue !== null)
+            return this.overrideValue.value;
+        return this.state.kind === 'value' ? this.state.value : undefined;
+    }
+    /**
+     * Derive a new `Lazy` whose value is `f(this.get())`.  The derivation
+     * is itself lazy — `map(f)` does not force the source.
+     */
+    map(f) {
+        return Lazy.of(() => f(this.get()));
+    }
+    /**
+     * Derive a new `Lazy` whose value flattens a `Lazy<Lazy<U>>`.  Same
+     * laziness contract as `map`.
+     */
+    flatMap(f) {
+        return Lazy.of(() => f(this.get()).get());
+    }
+    /**
+     * Run a side effect against the evaluated value.  Forces evaluation;
+     * idempotent by virtue of the cache.
+     */
+    forEach(f) { f(this.get()); }
+    /**
+     * Forget the memoised value so the next `get()` re-runs the thunk.
+     * Primarily a test hook — also clears any override set via
+     * `setOverride`.  In hot production paths, prefer building a new
+     * `Lazy` rather than resetting.
+     */
+    reset() {
+        this.state = { kind: 'pending' };
+        this.overrideValue = null;
+    }
+    /**
+     * Test hook: force `.get()` to return `value` without touching the
+     * thunk or the cache.  Call `reset()` (or `setOverride(null)`) to
+     * restore normal evaluation.
+     */
+    setOverride(value) {
+        this.overrideValue = value === null ? null : { value };
+    }
+}
+/** Shorthand alias matching Scala's `lazy val`. */
+export const lazy = Lazy.of;
+//# sourceMappingURL=Lazy.js.map

package/dist/util/Lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lazy.js","sourceRoot":"","sources":["../../src/util/Lazy.ts"],"names":[],"mappings":"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"}

package/dist/util/LazyImport.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Lazy-import helper for optional peer dependencies.
+ *
+ * Most of the framework's brokers + caches + persistence backends
+ * depend on optional peer-deps (`mqtt`, `kafkajs`, `memjs`, …).
+ * Before this helper existed, every site had its own try/catch around
+ * `import(name)` with a bespoke error message:
+ *
+ *   try {
+ *     const name = 'mqtt';
+ *     return (await import(name)) as unknown as MqttModule;
+ *   } catch (e) {
+ *     throw new Error('MqttActor requires the "mqtt" package.  ' +
+ *       'Install it with: npm install mqtt\nOriginal error: ' +
+ *       (e instanceof Error ? e.message : String(e)));
+ *   }
+ *
+ * ~7 lines per site, repeated ~10× across brokers + caches + journals,
+ * with subtle differences in wording.  This helper collapses each
+ * site to a single line.
+ *
+ * Usage:
+ *
+ *   const mqttLazy = Lazy.of(() => lazyImportModule<MqttModule>('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 auto-applied to 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 = fn`), others
+ * ESM (`export default fn`), 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.
+ */
+export interface LazyImportOptions {
+    /**
+     * 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.
+     */
+    readonly context?: string;
+    /**
+     * Override the suggested install command in the error message.
+     * Default: `npm install <name>`.
+     */
+    readonly installHint?: string;
+}
+/**
+ * Dynamic-import wrapper that produces a uniform "missing peer-dep"
+ * error message.
+ *
+ * Type-parameter `T` lets the caller assert the shape of the imported
+ * module — TypeScript can't infer the shape from a string-literal
+ * module name.
+ */
+export declare function lazyImportModule<T>(name: string, options?: LazyImportOptions): Promise<T>;
+//# sourceMappingURL=LazyImport.d.ts.map

package/dist/util/LazyImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyImport.d.ts","sourceRoot":"","sources":["../../src/util/LazyImport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/util/LazyImport.js

@@ -0,0 +1,64 @@
+/**
+ * Lazy-import helper for optional peer dependencies.
+ *
+ * Most of the framework's brokers + caches + persistence backends
+ * depend on optional peer-deps (`mqtt`, `kafkajs`, `memjs`, …).
+ * Before this helper existed, every site had its own try/catch around
+ * `import(name)` with a bespoke error message:
+ *
+ *   try {
+ *     const name = 'mqtt';
+ *     return (await import(name)) as unknown as MqttModule;
+ *   } catch (e) {
+ *     throw new Error('MqttActor requires the "mqtt" package.  ' +
+ *       'Install it with: npm install mqtt\nOriginal error: ' +
+ *       (e instanceof Error ? e.message : String(e)));
+ *   }
+ *
+ * ~7 lines per site, repeated ~10× across brokers + caches + journals,
+ * with subtle differences in wording.  This helper collapses each
+ * site to a single line.
+ *
+ * Usage:
+ *
+ *   const mqttLazy = Lazy.of(() => lazyImportModule<MqttModule>('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 auto-applied to 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 = fn`), others
+ * ESM (`export default fn`), 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.
+ */
+/**
+ * Dynamic-import wrapper that produces a uniform "missing peer-dep"
+ * error message.
+ *
+ * Type-parameter `T` lets the caller assert the shape of the imported
+ * module — TypeScript can't infer the shape from a string-literal
+ * module name.
+ */
+export async function lazyImportModule(name, options = {}) {
+    try {
+        return (await import(name));
+    }
+    catch (e) {
+        const context = options.context !== undefined ? `${options.context} requires` : `Required`;
+        const install = options.installHint ?? `npm install ${name}`;
+        throw new Error(`${context} the '${name}' package.  Install it with: ${install}\n` +
+            `Original error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+//# sourceMappingURL=LazyImport.js.map

package/dist/util/LazyImport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyImport.js","sourceRoot":"","sources":["../../src/util/LazyImport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAiBH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,UAA6B,EAAE;IAE/B,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAiB,CAAC;IAC9C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC;QAC3F,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,IAAI,eAAe,IAAI,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,SAAS,IAAI,gCAAgC,OAAO,IAAI;YAClE,mBAAmB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAChE,CAAC;IACJ,CAAC;AACH,CAAC"}