@benzenejs/self-host 0.0.0-stage → 0.1.0-beta.2

package/dist/BenzeneHost.d.ts

@@ -0,0 +1,100 @@
+import { IBenzeneServiceContainer } from '@benzenejs/abstractions';
+import { BenzeneStartUp, IBenzeneWorker } from '@benzenejs/abstractions-middleware';
+/** Options for {@link BenzeneHost.build}. */
+export interface BenzeneHostOptions {
+    /**
+     * Applied to the container **before** the startup's own `configureServices`, so a caller can
+     * substitute one of Benzene's baseline services (they are registered `tryAdd`-style: first
+     * registration wins). It is deliberately not a way to overrule the startup — the startup is the
+     * caller's own code and runs last. Same ordering rule, for the same reason, as .NET's
+     * `BenzeneHost.Build(args, configureHost)`.
+     */
+    configureServices?: (services: IBenzeneServiceContainer) => void;
+}
+/** Options for {@link BenzeneHost.runAsync} and {@link BenzeneHost.runWorkerAsync}. */
+export interface BenzeneRunOptions extends BenzeneHostOptions {
+    /** An extra shutdown trigger, in addition to the process signals. Aborting it stops the workers. */
+    signal?: AbortSignal;
+    /**
+     * The process signals that trigger shutdown. Defaults to `['SIGINT', 'SIGTERM']` — Ctrl-C and the
+     * signal Kubernetes/ECS send before the grace period. Pass `[]` to install no handlers at all and
+     * drive shutdown entirely through {@link signal}.
+     */
+    shutdownSignals?: readonly NodeJS.Signals[];
+}
+/**
+ * Runs a {@link BenzeneStartUp} as a long-running self-hosted worker process, so a service's entry
+ * point is one line:
+ *
+ * ```ts
+ * // main.ts, entire
+ * await BenzeneHost.runAsync(OrdersStartUp);
+ * ```
+ *
+ * The point is not the line count. It is that **the startup becomes the only place hosting is
+ * described** — transports are declared in `configure` via `useWorker(app, workers => …)`
+ * (`useSqs`, `useKafka`, `useRabbitMq`, `useServiceBus`, …), so adding a second one later never
+ * touches the entry point. An entry point that names a specific transport is one that has to be
+ * rewritten when the service grows another.
+ *
+ * **The explicit form this composes**, one level down, all public API — write it yourself whenever
+ * you need to do something in the middle of it:
+ *
+ * ```ts
+ * const startUp = new OrdersStartUp();
+ * const configuration = startUp.getConfiguration?.() ?? environmentConfiguration();
+ * const container = new DefaultBenzeneServiceContainer();   // @benzenejs/dependencies
+ * startUp.configureServices(container, configuration);
+ * const builder = new WorkerApplicationBuilder(container);  // @benzenejs/self-host
+ * startUp.configure(builder, configuration);
+ * const worker = builder.createWorker(
+ *   withStartUpChecks(container.createServiceResolverFactory()),  // @benzenejs/core-message-handlers
+ * );
+ * await worker.startAsync(signal);
+ * ```
+ *
+ * That is exactly what {@link build} does, and {@link build} hands the {@link IBenzeneWorker} back
+ * so you can start and stop it on your own terms — the rung between this and the block above.
+ *
+ * **When NOT to use it.** This owns the process's lifecycle. If Benzene is one part of a larger
+ * process — an Express app you already own, a gRPC `Server`, an AWS Lambda handler — do not run a
+ * host at all: mount Benzene into it with `benzene(...)` (`@benzenejs/express`), `useGrpc(...)`
+ * (`@benzenejs/grpc`) or `new AwsLambdaHost(StartUp)` (`@benzenejs/aws-lambda-core`).
+ *
+ * Port of the .NET `Benzene.HostedService.BenzeneHost`. .NET builds over
+ * `Host.CreateDefaultBuilder(args)` and registers an `IHostedService`; Node has no generic host, so
+ * this owns the signal handling and shutdown ordering directly and takes no `args`.
+ */
+export declare class BenzeneHost {
+    /**
+     * Builds the worker for `startUpFactory` without starting it — the escape hatch, and the seam a
+     * test uses. Runs the boot-time wiring checks (`withStartUpChecks`) before returning, so a
+     * registration mistake is a start-up failure rather than every message failing to route once the
+     * loop is live.
+     *
+     * @param startUpFactory A no-argument constructor for the startup — the port of C#'s
+     *   `where TStartUp : BenzeneStartUp, new()`.
+     */
+    static build<TStartUp extends BenzeneStartUp>(startUpFactory: new () => TStartUp, options?: BenzeneHostOptions): IBenzeneWorker;
+    /**
+     * Builds the worker for `startUpFactory` and runs it until a shutdown signal arrives, then stops it.
+     * Composed from {@link build} + {@link runWorkerAsync}; drop to either when you need to do something
+     * between the two.
+     */
+    static runAsync<TStartUp extends BenzeneStartUp>(startUpFactory: new () => TStartUp, options?: BenzeneRunOptions): Promise<void>;
+    /**
+     * Runs an already-built {@link IBenzeneWorker} until shutdown: installs the shutdown-signal
+     * handlers, starts the worker, waits for a shutdown signal, then stops it and removes the handlers.
+     * The wait is for the *signal*, not for the workers - `startAsync` resolving means "started", not
+     * "finished". A worker that fails to start triggers shutdown itself, so the process never hangs on a
+     * signal that will not come.
+     *
+     * This is the rung for a worker you built some other way — {@link build}, an
+     * {@link InlineSelfHostedStartUp}, or a hand-written {@link IBenzeneWorker}. The explicit form it
+     * composes is `worker.startAsync(signal)` / `worker.stopAsync()` with your own
+     * `process.on('SIGTERM', …)`.
+     *
+     * A start failure is rethrown once the workers have been stopped.
+     */
+    static runWorkerAsync(worker: IBenzeneWorker, options?: BenzeneRunOptions): Promise<void>;
+}

package/dist/BenzeneHost.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenzeneHost = void 0;
+const abstractions_middleware_1 = require("@benzenejs/abstractions-middleware");
+const core_message_handlers_1 = require("@benzenejs/core-message-handlers");
+const dependencies_1 = require("@benzenejs/dependencies");
+const WorkerApplicationBuilder_1 = require("./WorkerApplicationBuilder");
+/**
+ * Runs a {@link BenzeneStartUp} as a long-running self-hosted worker process, so a service's entry
+ * point is one line:
+ *
+ * ```ts
+ * // main.ts, entire
+ * await BenzeneHost.runAsync(OrdersStartUp);
+ * ```
+ *
+ * The point is not the line count. It is that **the startup becomes the only place hosting is
+ * described** — transports are declared in `configure` via `useWorker(app, workers => …)`
+ * (`useSqs`, `useKafka`, `useRabbitMq`, `useServiceBus`, …), so adding a second one later never
+ * touches the entry point. An entry point that names a specific transport is one that has to be
+ * rewritten when the service grows another.
+ *
+ * **The explicit form this composes**, one level down, all public API — write it yourself whenever
+ * you need to do something in the middle of it:
+ *
+ * ```ts
+ * const startUp = new OrdersStartUp();
+ * const configuration = startUp.getConfiguration?.() ?? environmentConfiguration();
+ * const container = new DefaultBenzeneServiceContainer();   // @benzenejs/dependencies
+ * startUp.configureServices(container, configuration);
+ * const builder = new WorkerApplicationBuilder(container);  // @benzenejs/self-host
+ * startUp.configure(builder, configuration);
+ * const worker = builder.createWorker(
+ *   withStartUpChecks(container.createServiceResolverFactory()),  // @benzenejs/core-message-handlers
+ * );
+ * await worker.startAsync(signal);
+ * ```
+ *
+ * That is exactly what {@link build} does, and {@link build} hands the {@link IBenzeneWorker} back
+ * so you can start and stop it on your own terms — the rung between this and the block above.
+ *
+ * **When NOT to use it.** This owns the process's lifecycle. If Benzene is one part of a larger
+ * process — an Express app you already own, a gRPC `Server`, an AWS Lambda handler — do not run a
+ * host at all: mount Benzene into it with `benzene(...)` (`@benzenejs/express`), `useGrpc(...)`
+ * (`@benzenejs/grpc`) or `new AwsLambdaHost(StartUp)` (`@benzenejs/aws-lambda-core`).
+ *
+ * Port of the .NET `Benzene.HostedService.BenzeneHost`. .NET builds over
+ * `Host.CreateDefaultBuilder(args)` and registers an `IHostedService`; Node has no generic host, so
+ * this owns the signal handling and shutdown ordering directly and takes no `args`.
+ */
+class BenzeneHost {
+    /**
+     * Builds the worker for `startUpFactory` without starting it — the escape hatch, and the seam a
+     * test uses. Runs the boot-time wiring checks (`withStartUpChecks`) before returning, so a
+     * registration mistake is a start-up failure rather than every message failing to route once the
+     * loop is live.
+     *
+     * @param startUpFactory A no-argument constructor for the startup — the port of C#'s
+     *   `where TStartUp : BenzeneStartUp, new()`.
+     */
+    static build(startUpFactory, options = {}) {
+        const startUp = new startUpFactory();
+        const configuration = startUp.getConfiguration?.() ?? (0, abstractions_middleware_1.environmentConfiguration)();
+        const container = new dependencies_1.DefaultBenzeneServiceContainer();
+        // Before the startup's own registrations: see BenzeneHostOptions.configureServices.
+        options.configureServices?.(container);
+        startUp.configureServices(container, configuration);
+        const builder = new WorkerApplicationBuilder_1.WorkerApplicationBuilder(container);
+        startUp.configure(builder, configuration);
+        return builder.createWorker((0, core_message_handlers_1.withStartUpChecks)(container.createServiceResolverFactory()));
+    }
+    /**
+     * Builds the worker for `startUpFactory` and runs it until a shutdown signal arrives, then stops it.
+     * Composed from {@link build} + {@link runWorkerAsync}; drop to either when you need to do something
+     * between the two.
+     */
+    static async runAsync(startUpFactory, options = {}) {
+        await BenzeneHost.runWorkerAsync(BenzeneHost.build(startUpFactory, options), options);
+    }
+    /**
+     * Runs an already-built {@link IBenzeneWorker} until shutdown: installs the shutdown-signal
+     * handlers, starts the worker, waits for a shutdown signal, then stops it and removes the handlers.
+     * The wait is for the *signal*, not for the workers - `startAsync` resolving means "started", not
+     * "finished". A worker that fails to start triggers shutdown itself, so the process never hangs on a
+     * signal that will not come.
+     *
+     * This is the rung for a worker you built some other way — {@link build}, an
+     * {@link InlineSelfHostedStartUp}, or a hand-written {@link IBenzeneWorker}. The explicit form it
+     * composes is `worker.startAsync(signal)` / `worker.stopAsync()` with your own
+     * `process.on('SIGTERM', …)`.
+     *
+     * A start failure is rethrown once the workers have been stopped.
+     */
+    static async runWorkerAsync(worker, options = {}) {
+        const controller = new AbortController();
+        const abort = () => {
+            controller.abort();
+        };
+        const signals = options.shutdownSignals ?? ['SIGINT', 'SIGTERM'];
+        for (const name of signals) {
+            process.on(name, abort);
+        }
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted === true) {
+            controller.abort();
+        }
+        const shutdown = new Promise((resolve) => {
+            if (controller.signal.aborted) {
+                resolve();
+                return;
+            }
+            controller.signal.addEventListener('abort', () => resolve(), { once: true });
+        });
+        try {
+            const running = worker.startAsync(controller.signal);
+            // The host runs until it is told to stop, NOT until the workers finish: `startAsync` resolves
+            // promptly for a push-based worker (a Kafka consumer, an HTTP listener) and only on shutdown for
+            // a polling one, so "all workers resolved" is not a reason to exit. A worker that fails to start
+            // is, though - it triggers the same shutdown rather than leaving the process waiting on a signal
+            // that will never come.
+            running.catch(() => controller.abort());
+            await shutdown;
+            await worker.stopAsync();
+            // Now that stop has run the loops unwind; this rethrows a start failure (already handled above,
+            // so it never surfaces as an unhandled rejection) or anything they threw on the way out.
+            await running;
+        }
+        finally {
+            for (const name of signals) {
+                process.off(name, abort);
+            }
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+}
+exports.BenzeneHost = BenzeneHost;

package/dist/BenzeneWorkerBuilder.d.ts

@@ -0,0 +1,21 @@
+import { IBenzeneServiceContainer, IServiceResolverFactory } from '@benzenejs/abstractions';
+import { IBenzeneWorker, IMiddlewarePipelineBuilder } from '@benzenejs/abstractions-middleware';
+import { IBenzeneWorkerStartup } from './IBenzeneWorkerStartup';
+/**
+ * Default {@link IBenzeneWorkerStartup}: collects worker factories and, at host start, materializes them
+ * into one {@link CompositeBenzeneWorker} bound to the invocation's resolver factory.
+ * Port of Benzene.SelfHost.BenzeneWorkerBuilder.
+ *
+ * C#'s `IBenzeneWorkerStartup.Create(IServiceResolverFactory)` (the worker-materialization overload of
+ * `Create`) is named `createWorker` here to disambiguate from the generic pipeline-builder `create`,
+ * since TypeScript can't overload a generic no-arg method against a one-arg method as cleanly as C#.
+ */
+export declare class BenzeneWorkerBuilder implements IBenzeneWorkerStartup {
+    private readonly benzeneServiceContainer;
+    private readonly apps;
+    constructor(benzeneServiceContainer: IBenzeneServiceContainer);
+    add(func: (serviceResolverFactory: IServiceResolverFactory) => IBenzeneWorker): void;
+    register(action: (container: IBenzeneServiceContainer) => void): void;
+    create<TNewContext>(): IMiddlewarePipelineBuilder<TNewContext>;
+    createWorker(serviceResolverFactory: IServiceResolverFactory): IBenzeneWorker;
+}

package/dist/BenzeneWorkerBuilder.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenzeneWorkerBuilder = void 0;
+const core_middleware_1 = require("@benzenejs/core-middleware");
+const CompositeBenzeneWorker_1 = require("./CompositeBenzeneWorker");
+/**
+ * Default {@link IBenzeneWorkerStartup}: collects worker factories and, at host start, materializes them
+ * into one {@link CompositeBenzeneWorker} bound to the invocation's resolver factory.
+ * Port of Benzene.SelfHost.BenzeneWorkerBuilder.
+ *
+ * C#'s `IBenzeneWorkerStartup.Create(IServiceResolverFactory)` (the worker-materialization overload of
+ * `Create`) is named `createWorker` here to disambiguate from the generic pipeline-builder `create`,
+ * since TypeScript can't overload a generic no-arg method against a one-arg method as cleanly as C#.
+ */
+class BenzeneWorkerBuilder {
+    benzeneServiceContainer;
+    apps = [];
+    constructor(benzeneServiceContainer) {
+        this.benzeneServiceContainer = benzeneServiceContainer;
+    }
+    add(func) {
+        this.apps.push(func);
+    }
+    register(action) {
+        action(this.benzeneServiceContainer);
+    }
+    create() {
+        return new core_middleware_1.MiddlewarePipelineBuilder(this.benzeneServiceContainer);
+    }
+    createWorker(serviceResolverFactory) {
+        return new CompositeBenzeneWorker_1.CompositeBenzeneWorker(this.apps.map((x) => x(serviceResolverFactory)));
+    }
+}
+exports.BenzeneWorkerBuilder = BenzeneWorkerBuilder;

package/dist/BoundedChannel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A bounded, capacity-1, single-reader / multi-writer async channel - the subset of
+ * `System.Threading.Channels.Channel<T>` (created via `Channel.CreateBounded<T>(new
+ * BoundedChannelOptions(1) { SingleReader = true, SingleWriter = false, FullMode = Wait })`) that
+ * {@link BoundedConcurrentDispatcher} relies on. .NET ships Channels in the BCL; Node has no
+ * equivalent, so the used behaviour is re-created here (same pattern as `@benzenejs/rate-limiting`
+ * re-creating the `System.Threading.RateLimiting` subset).
+ *
+ * `write` resolves once the single slot is free (giving the producer backpressure); `complete` closes
+ * the channel so a pending/next `write` rejects and the `readAll` iterator finishes once drained. Node
+ * is single-threaded, so no locking is needed - the fields are only ever touched between `await`
+ * points on one event loop.
+ */
+/** Thrown by {@link BoundedChannel.write} when the channel has been completed. Port of `ChannelClosedException`. */
+export declare class ChannelCompletedError extends Error {
+    constructor();
+}
+export declare class BoundedChannel<T> {
+    private slot;
+    private hasItem;
+    private completed;
+    private readonly readWaiters;
+    private readonly writeWaiters;
+    /**
+     * Writes an item, waiting while the single slot is occupied (capacity-1 backpressure). Rejects with
+     * {@link ChannelCompletedError} if the channel is (or becomes) completed, or with the signal's reason
+     * if `signal` aborts while waiting.
+     */
+    write(item: T, signal?: AbortSignal): Promise<void>;
+    /** Closes the channel: no further items are accepted, and `readAll` ends once the current item (if any) is read. */
+    complete(): void;
+    /** The single consumer's loop: yields each written item in order, returning when completed and drained. */
+    readAll(): AsyncIterableIterator<T>;
+    private wait;
+    /**
+     * Wakes every waiter; each re-checks its own condition on resume (a freed slot only lets one writer
+     * proceed, the rest re-wait), so spurious wake-ups are harmless.
+     */
+    private wake;
+}

package/dist/BoundedChannel.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * A bounded, capacity-1, single-reader / multi-writer async channel - the subset of
+ * `System.Threading.Channels.Channel<T>` (created via `Channel.CreateBounded<T>(new
+ * BoundedChannelOptions(1) { SingleReader = true, SingleWriter = false, FullMode = Wait })`) that
+ * {@link BoundedConcurrentDispatcher} relies on. .NET ships Channels in the BCL; Node has no
+ * equivalent, so the used behaviour is re-created here (same pattern as `@benzenejs/rate-limiting`
+ * re-creating the `System.Threading.RateLimiting` subset).
+ *
+ * `write` resolves once the single slot is free (giving the producer backpressure); `complete` closes
+ * the channel so a pending/next `write` rejects and the `readAll` iterator finishes once drained. Node
+ * is single-threaded, so no locking is needed - the fields are only ever touched between `await`
+ * points on one event loop.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedChannel = exports.ChannelCompletedError = void 0;
+/** Thrown by {@link BoundedChannel.write} when the channel has been completed. Port of `ChannelClosedException`. */
+class ChannelCompletedError extends Error {
+    constructor() {
+        super('The channel has been completed and cannot accept further writes.');
+        this.name = 'ChannelCompletedError';
+    }
+}
+exports.ChannelCompletedError = ChannelCompletedError;
+class BoundedChannel {
+    slot;
+    hasItem = false;
+    completed = false;
+    readWaiters = [];
+    writeWaiters = [];
+    /**
+     * Writes an item, waiting while the single slot is occupied (capacity-1 backpressure). Rejects with
+     * {@link ChannelCompletedError} if the channel is (or becomes) completed, or with the signal's reason
+     * if `signal` aborts while waiting.
+     */
+    async write(item, signal) {
+        while (this.hasItem && !this.completed) {
+            await this.wait(this.writeWaiters, signal);
+        }
+        if (this.completed) {
+            throw new ChannelCompletedError();
+        }
+        this.slot = item;
+        this.hasItem = true;
+        this.wake(this.readWaiters);
+    }
+    /** Closes the channel: no further items are accepted, and `readAll` ends once the current item (if any) is read. */
+    complete() {
+        this.completed = true;
+        this.wake(this.readWaiters);
+        this.wake(this.writeWaiters);
+    }
+    /** The single consumer's loop: yields each written item in order, returning when completed and drained. */
+    async *readAll() {
+        for (;;) {
+            while (!this.hasItem && !this.completed) {
+                await this.wait(this.readWaiters);
+            }
+            if (this.hasItem) {
+                const item = this.slot;
+                this.slot = undefined;
+                this.hasItem = false;
+                this.wake(this.writeWaiters);
+                yield item;
+            }
+            else {
+                return; // completed and empty
+            }
+        }
+    }
+    wait(waiters, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            const onResolve = () => {
+                cleanup();
+                resolve();
+            };
+            const onAbort = () => {
+                const index = waiters.indexOf(onResolve);
+                if (index >= 0) {
+                    waiters.splice(index, 1);
+                }
+                cleanup();
+                reject(signal?.reason);
+            };
+            const cleanup = () => signal?.removeEventListener('abort', onAbort);
+            waiters.push(onResolve);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /**
+     * Wakes every waiter; each re-checks its own condition on resume (a freed slot only lets one writer
+     * proceed, the rest re-wait), so spurious wake-ups are harmless.
+     */
+    wake(waiters) {
+        const pending = waiters.splice(0);
+        for (const resolve of pending) {
+            resolve();
+        }
+    }
+}
+exports.BoundedChannel = BoundedChannel;

package/dist/BoundedConcurrentDispatcher.d.ts

@@ -0,0 +1,72 @@
+import { ILogger } from '@benzenejs/abstractions';
+/** The async handler each dispatched item is passed to. Port of C# `Func<T, CancellationToken, Task>`. */
+export type DispatchHandler<T> = (item: T, cancellationToken?: AbortSignal) => Promise<void>;
+/** Optional configuration for {@link BoundedConcurrentDispatcher}. Ports the C# constructor's optional parameters. */
+export interface BoundedConcurrentDispatcherOptions<T> {
+    /**
+     * When provided, routes items sharing the same key to the same lane, preserving per-key order. When
+     * omitted (the default), items round-robin across lanes with no ordering guarantee.
+     */
+    keySelector?: (item: T) => number;
+    /**
+     * When `true` (the default), a fault from `handle` is logged and swallowed - that lane keeps
+     * consuming. When `false`, the fault is logged, passed to `onFault` if supplied, and rethrown -
+     * ending that lane's consume loop.
+     */
+    catchExceptions?: boolean;
+    /**
+     * Invoked with the fault when `catchExceptions` is `false` and `handle` throws, before the fault is
+     * rethrown. Lets a caller react to a lane dying (e.g. stop the whole worker).
+     */
+    onFault?: (error: unknown) => void;
+}
+/**
+ * Dispatches items pulled from a self-hosted worker's poll loop to an async handler, bounding how many
+ * handlers run at once. Built on a capacity-1 {@link BoundedChannel} per lane - the port's stand-in
+ * for `System.Threading.Channels`.
+ * Port of Benzene.SelfHost.BoundedConcurrentDispatcher&lt;T&gt;.
+ *
+ * Runs `laneCount` independent lanes, each a single-consumer channel with one dedicated consumer. With
+ * a `keySelector`, items sharing a key always route to the same lane, so that lane's strictly-FIFO
+ * consumer preserves order for that key while different keys run concurrently, up to `laneCount` at
+ * once. Without one, items round-robin with no ordering promise. Each lane's channel has capacity 1, so
+ * `enqueueAsync` blocks once a lane already has one item queued behind the one in flight - the poll
+ * loop's backpressure.
+ *
+ * Node is single-threaded, so C#'s `Interlocked`/`Volatile` accesses on the outstanding-count array and
+ * round-robin counter become plain reads/writes (only ever touched between `await` points on one event
+ * loop); C#'s `ILogger` maps to `@benzenejs/abstractions`' `ILogger`.
+ */
+export declare class BoundedConcurrentDispatcher<T> {
+    private readonly logger;
+    private readonly lanes;
+    private readonly consumers;
+    private readonly keySelector?;
+    private readonly laneOutstanding;
+    private roundRobinCounter;
+    constructor(laneCount: number, handle: DispatchHandler<T>, logger: ILogger, options?: BoundedConcurrentDispatcherOptions<T>);
+    /** The number of lanes items are dispatched across. */
+    get laneCount(): number;
+    /** Maps a key to the lane index it routes to (the same mapping {@link enqueueAsync} uses). */
+    laneForKey(key: number): number;
+    /**
+     * Routes `item` to a lane (by key, if a key selector was supplied, otherwise round-robin) and
+     * enqueues it for that lane's consumer to dispatch.
+     */
+    enqueueAsync(item: T, cancellationToken?: AbortSignal): Promise<void>;
+    /**
+     * Waits for the lanes the given keys route to (via {@link laneForKey}) to have no items queued or in
+     * flight, up to `timeoutMs` - without completing them, so those lanes keep consuming afterwards.
+     * Because lanes are shared (`key % laneCount`), this may also wait on unrelated keys that share a
+     * lane - safe, just conservative.
+     */
+    drainLanesAsync(laneKeys: Iterable<number>, timeoutMs: number): Promise<void>;
+    /**
+     * Stops accepting new items on every lane and waits for all in-flight handler calls to finish, up to
+     * `drainTimeoutMs`. Lanes that haven't finished by the timeout are abandoned, not cancelled - `handle`
+     * is responsible for honoring its own cancellation, if any.
+     */
+    drainAsync(drainTimeoutMs: number): Promise<void>;
+    private consumeLoopAsync;
+    private consumeLaneAsync;
+}

package/dist/BoundedConcurrentDispatcher.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedConcurrentDispatcher = void 0;
+const BoundedChannel_1 = require("./BoundedChannel");
+/**
+ * Dispatches items pulled from a self-hosted worker's poll loop to an async handler, bounding how many
+ * handlers run at once. Built on a capacity-1 {@link BoundedChannel} per lane - the port's stand-in
+ * for `System.Threading.Channels`.
+ * Port of Benzene.SelfHost.BoundedConcurrentDispatcher<T>.
+ *
+ * Runs `laneCount` independent lanes, each a single-consumer channel with one dedicated consumer. With
+ * a `keySelector`, items sharing a key always route to the same lane, so that lane's strictly-FIFO
+ * consumer preserves order for that key while different keys run concurrently, up to `laneCount` at
+ * once. Without one, items round-robin with no ordering promise. Each lane's channel has capacity 1, so
+ * `enqueueAsync` blocks once a lane already has one item queued behind the one in flight - the poll
+ * loop's backpressure.
+ *
+ * Node is single-threaded, so C#'s `Interlocked`/`Volatile` accesses on the outstanding-count array and
+ * round-robin counter become plain reads/writes (only ever touched between `await` points on one event
+ * loop); C#'s `ILogger` maps to `@benzenejs/abstractions`' `ILogger`.
+ */
+class BoundedConcurrentDispatcher {
+    logger;
+    lanes;
+    consumers;
+    keySelector;
+    laneOutstanding;
+    roundRobinCounter = -1;
+    constructor(laneCount, handle, logger, options = {}) {
+        this.logger = logger;
+        if (laneCount < 1) {
+            throw new RangeError(`laneCount must be at least 1 (was ${laneCount}).`);
+        }
+        this.keySelector = options.keySelector;
+        const catchExceptions = options.catchExceptions ?? true;
+        this.lanes = Array.from({ length: laneCount }, () => new BoundedChannel_1.BoundedChannel());
+        this.laneOutstanding = new Array(laneCount).fill(0);
+        this.consumers = this.lanes.map((_, i) => {
+            const consumer = this.consumeLoopAsync(i, handle, catchExceptions, options.onFault);
+            // A lane consumer rejects when catchExceptions=false and its handler faults. Observe it here so
+            // the rejection is never "unhandled" before drainAsync awaits it (drainAsync uses allSettled, so
+            // it never surfaces as a throw either - matching C#'s `Task.WhenAny`, which ignores a faulted task).
+            void consumer.catch(() => { });
+            return consumer;
+        });
+    }
+    /** The number of lanes items are dispatched across. */
+    get laneCount() {
+        return this.lanes.length;
+    }
+    /** Maps a key to the lane index it routes to (the same mapping {@link enqueueAsync} uses). */
+    laneForKey(key) {
+        // `>>> 0` reinterprets as uint32, matching C#'s `(uint)key % (uint)laneCount` for negative keys.
+        return (key >>> 0) % this.lanes.length;
+    }
+    /**
+     * Routes `item` to a lane (by key, if a key selector was supplied, otherwise round-robin) and
+     * enqueues it for that lane's consumer to dispatch.
+     */
+    async enqueueAsync(item, cancellationToken) {
+        const laneIndex = this.keySelector !== undefined
+            ? (this.keySelector(item) >>> 0) % this.lanes.length
+            : (++this.roundRobinCounter >>> 0) % this.lanes.length;
+        // Count the item as outstanding for its lane from the moment it's accepted (queued or in flight)
+        // until its handler finishes - this is what drainLanesAsync waits on. If the write is
+        // cancelled/faulted it never entered the lane, so undo the increment.
+        this.laneOutstanding[laneIndex]++;
+        try {
+            await this.lanes[laneIndex].write(item, cancellationToken);
+        }
+        catch (ex) {
+            this.laneOutstanding[laneIndex]--;
+            throw ex;
+        }
+    }
+    /**
+     * Waits for the lanes the given keys route to (via {@link laneForKey}) to have no items queued or in
+     * flight, up to `timeoutMs` - without completing them, so those lanes keep consuming afterwards.
+     * Because lanes are shared (`key % laneCount`), this may also wait on unrelated keys that share a
+     * lane - safe, just conservative.
+     */
+    async drainLanesAsync(laneKeys, timeoutMs) {
+        const targetLanes = [...new Set([...laneKeys].map((k) => this.laneForKey(k)))];
+        if (targetLanes.length === 0) {
+            return;
+        }
+        const start = Date.now();
+        while (targetLanes.some((i) => this.laneOutstanding[i] > 0)) {
+            if (Date.now() - start >= timeoutMs) {
+                return;
+            }
+            await delay(10);
+        }
+    }
+    /**
+     * Stops accepting new items on every lane and waits for all in-flight handler calls to finish, up to
+     * `drainTimeoutMs`. Lanes that haven't finished by the timeout are abandoned, not cancelled - `handle`
+     * is responsible for honoring its own cancellation, if any.
+     */
+    async drainAsync(drainTimeoutMs) {
+        for (const lane of this.lanes) {
+            lane.complete();
+        }
+        // allSettled (not all) so a faulted lane consumer doesn't make drain reject - C#'s `Task.WhenAny`
+        // returns the faulted task without observing it; the equivalent here is to wait on settlement.
+        await Promise.race([Promise.allSettled(this.consumers), delay(drainTimeoutMs)]);
+    }
+    async consumeLoopAsync(laneIndex, handle, catchExceptions, onFault) {
+        try {
+            await this.consumeLaneAsync(laneIndex, handle, catchExceptions, onFault);
+        }
+        finally {
+            // The lane consumer is exiting - either normal completion (the count is already 0) or a rethrown
+            // fault with catchExceptions=false. On the fault path any item still queued in this lane's
+            // channel was counted at enqueue and will never be read now, so clear the phantom count -
+            // otherwise a later drainLanesAsync on this lane would burn its full timeout every time.
+            this.laneOutstanding[laneIndex] = 0;
+        }
+    }
+    async consumeLaneAsync(laneIndex, handle, catchExceptions, onFault) {
+        for await (const item of this.lanes[laneIndex].readAll()) {
+            try {
+                await handle(item);
+            }
+            catch (ex) {
+                this.logger.logError(ex, 'Unhandled exception processing item in Benzene worker loop');
+                if (!catchExceptions) {
+                    onFault?.(ex);
+                    throw ex;
+                }
+            }
+            finally {
+                // Runs on every path - success, swallowed exception, and the rethrow above - so each item is
+                // un-counted exactly once and a quiescing drainLanesAsync never hangs on a dying lane.
+                this.laneOutstanding[laneIndex]--;
+            }
+        }
+    }
+}
+exports.BoundedConcurrentDispatcher = BoundedConcurrentDispatcher;
+/** A cancellable delay. `Task.Delay(TimeSpan)` -> a `setTimeout`-backed promise. */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/CompositeBenzeneWorker.d.ts

@@ -0,0 +1,11 @@
+import { IBenzeneWorker } from '@benzenejs/abstractions-middleware';
+/**
+ * Aggregates several {@link IBenzeneWorker}s as one, starting and stopping them together.
+ * Port of Benzene.SelfHost.CompositeBenzeneWorker.
+ */
+export declare class CompositeBenzeneWorker implements IBenzeneWorker {
+    private readonly workers;
+    constructor(workers: Iterable<IBenzeneWorker>);
+    startAsync(cancellationToken?: AbortSignal): Promise<void>;
+    stopAsync(cancellationToken?: AbortSignal): Promise<void>;
+}

package/dist/CompositeBenzeneWorker.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeBenzeneWorker = void 0;
+/**
+ * Aggregates several {@link IBenzeneWorker}s as one, starting and stopping them together.
+ * Port of Benzene.SelfHost.CompositeBenzeneWorker.
+ */
+class CompositeBenzeneWorker {
+    workers;
+    constructor(workers) {
+        // Materialize once. Callers pass a deferred sequence (BenzeneWorkerBuilder.create hands us
+        // `apps.map(factory => factory(resolver))`, and every factory news up a fresh worker), so
+        // re-enumerating in stopAsync would build a SECOND, never-started worker set and stop those
+        // instead - silently skipping every worker's drain/close/commit. `[...workers]` snapshots it.
+        this.workers = [...workers];
+    }
+    async startAsync(cancellationToken) {
+        await Promise.all(this.workers.map((x) => x.startAsync(cancellationToken)));
+    }
+    async stopAsync(cancellationToken) {
+        await Promise.all(this.workers.map((x) => x.stopAsync(cancellationToken)));
+    }
+}
+exports.CompositeBenzeneWorker = CompositeBenzeneWorker;

package/dist/IBenzeneWorkerStartup.d.ts

@@ -0,0 +1,16 @@
+import { IRegisterDependency, IServiceResolverFactory } from '@benzenejs/abstractions';
+import { IBenzeneWorker, IMiddlewarePipelineBuilder } from '@benzenejs/abstractions-middleware';
+/**
+ * The worker-registration surface a self-hosted `BenzeneStartUp.Configure` builds against: register
+ * worker factories, create per-context middleware pipelines, and (at host start) materialize the
+ * composite worker for a given resolver factory.
+ * Port of Benzene.SelfHost.IBenzeneWorkerStartup.
+ */
+export interface IBenzeneWorkerStartup extends IRegisterDependency {
+    /** Registers a factory that builds one worker from the invocation's resolver factory. */
+    add(func: (serviceResolverFactory: IServiceResolverFactory) => IBenzeneWorker): void;
+    /** Creates a middleware pipeline builder for a new context type. */
+    create<TNewContext>(): IMiddlewarePipelineBuilder<TNewContext>;
+    /** Materializes all registered workers as a single composite worker over the given resolver factory. */
+    createWorker(serviceResolverFactory: IServiceResolverFactory): IBenzeneWorker;
+}

package/dist/IBenzeneWorkerStartup.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/InlineSelfHostedStartUp.d.ts

@@ -0,0 +1,24 @@
+import { IBenzeneServiceContainer } from '@benzenejs/abstractions';
+import { IBenzeneWorker } from '@benzenejs/abstractions-middleware';
+import { IBenzeneWorkerStartup } from './IBenzeneWorkerStartup';
+/** Builds a ready-to-run {@link IBenzeneWorker}. Port of Benzene.SelfHost.IBenzeneWorkerBuilder. */
+export interface IBenzeneWorkerBuilder {
+    build(): IBenzeneWorker;
+}
+/**
+ * A minimal, fluent self-hosted startup: register services and configure workers inline, then `build`
+ * a composite worker - the no-ceremony alternative to a full `BenzeneStartUp` subclass.
+ * Port of Benzene.SelfHost.InlineSelfHostedStartUp.
+ *
+ * C# builds over `new ServiceCollection()` + `MicrosoftBenzeneServiceContainer`/
+ * `MicrosoftServiceResolverFactory`; the port uses `DefaultBenzeneServiceContainer` from
+ * `@benzenejs/dependencies`, which is both the registration surface and the resolver-factory source - so
+ * C#'s separate `Action<IServiceCollection>` becomes an `Action<IBenzeneServiceContainer>`.
+ */
+export declare class InlineSelfHostedStartUp implements IBenzeneWorkerBuilder {
+    private servicesAction;
+    private appAction;
+    configureServices(action: (container: IBenzeneServiceContainer) => void): InlineSelfHostedStartUp;
+    configure(action: (app: IBenzeneWorkerStartup) => void): InlineSelfHostedStartUp;
+    build(): IBenzeneWorker;
+}

package/dist/InlineSelfHostedStartUp.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InlineSelfHostedStartUp = void 0;
+const core_message_handlers_1 = require("@benzenejs/core-message-handlers");
+const dependencies_1 = require("@benzenejs/dependencies");
+const BenzeneWorkerBuilder_1 = require("./BenzeneWorkerBuilder");
+/**
+ * A minimal, fluent self-hosted startup: register services and configure workers inline, then `build`
+ * a composite worker - the no-ceremony alternative to a full `BenzeneStartUp` subclass.
+ * Port of Benzene.SelfHost.InlineSelfHostedStartUp.
+ *
+ * C# builds over `new ServiceCollection()` + `MicrosoftBenzeneServiceContainer`/
+ * `MicrosoftServiceResolverFactory`; the port uses `DefaultBenzeneServiceContainer` from
+ * `@benzenejs/dependencies`, which is both the registration surface and the resolver-factory source - so
+ * C#'s separate `Action<IServiceCollection>` becomes an `Action<IBenzeneServiceContainer>`.
+ */
+class InlineSelfHostedStartUp {
+    servicesAction = () => { };
+    appAction = () => { };
+    configureServices(action) {
+        this.servicesAction = action;
+        return this;
+    }
+    configure(action) {
+        this.appAction = action;
+        return this;
+    }
+    build() {
+        const container = new dependencies_1.DefaultBenzeneServiceContainer();
+        const app = new BenzeneWorkerBuilder_1.BenzeneWorkerBuilder(container);
+        this.appAction(app);
+        this.servicesAction(container);
+        // Run the boot-time wiring checks before the worker goes live, exactly as every other host does
+        // (AwsLambdaStartUpRunner, AzureFunctionStartUpRunner, GoogleCloudFunctionHost, BenzeneHost) - a
+        // registration mistake fails the build here rather than on the first polled message.
+        return app.createWorker((0, core_message_handlers_1.withStartUpChecks)(container.createServiceResolverFactory()));
+    }
+}
+exports.InlineSelfHostedStartUp = InlineSelfHostedStartUp;

package/dist/WorkerApplicationBuilder.d.ts

@@ -0,0 +1,22 @@
+import { IBenzeneServiceContainer, IServiceResolverFactory } from '@benzenejs/abstractions';
+import { IBenzeneApplicationBuilder, IBenzeneWorker } from '@benzenejs/abstractions-middleware';
+import { BenzeneApplicationBuilder } from '@benzenejs/core-middleware';
+import { IBenzeneWorkerStartup } from './IBenzeneWorkerStartup';
+/**
+ * The `IBenzeneApplicationBuilder` for the self-hosted worker platform ("Worker"): adds a worker
+ * registry (`workers`) alongside the base pipeline/registration plumbing, and materializes the
+ * composite worker at host start.
+ * Port of Benzene.SelfHost.WorkerApplicationBuilder.
+ */
+export declare class WorkerApplicationBuilder extends BenzeneApplicationBuilder {
+    static readonly platformName = "Worker";
+    private readonly workerStartup;
+    constructor(benzeneServiceContainer: IBenzeneServiceContainer);
+    get workers(): IBenzeneWorkerStartup;
+    createWorker(serviceResolverFactory: IServiceResolverFactory): IBenzeneWorker;
+}
+/**
+ * Applies worker-host-specific configuration; a no-op on other platforms. Port of the C# extension
+ * method `UseWorker` -> a free function taking the builder first.
+ */
+export declare function useWorker(app: IBenzeneApplicationBuilder, configure: (workers: IBenzeneWorkerStartup) => void): IBenzeneApplicationBuilder;

package/dist/WorkerApplicationBuilder.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerApplicationBuilder = void 0;
+exports.useWorker = useWorker;
+const core_middleware_1 = require("@benzenejs/core-middleware");
+const BenzeneWorkerBuilder_1 = require("./BenzeneWorkerBuilder");
+/**
+ * The `IBenzeneApplicationBuilder` for the self-hosted worker platform ("Worker"): adds a worker
+ * registry (`workers`) alongside the base pipeline/registration plumbing, and materializes the
+ * composite worker at host start.
+ * Port of Benzene.SelfHost.WorkerApplicationBuilder.
+ */
+class WorkerApplicationBuilder extends core_middleware_1.BenzeneApplicationBuilder {
+    static platformName = 'Worker';
+    workerStartup;
+    constructor(benzeneServiceContainer) {
+        super(WorkerApplicationBuilder.platformName, benzeneServiceContainer);
+        this.workerStartup = new BenzeneWorkerBuilder_1.BenzeneWorkerBuilder(benzeneServiceContainer);
+    }
+    get workers() {
+        return this.workerStartup;
+    }
+    createWorker(serviceResolverFactory) {
+        return this.workerStartup.createWorker(serviceResolverFactory);
+    }
+}
+exports.WorkerApplicationBuilder = WorkerApplicationBuilder;
+/**
+ * Applies worker-host-specific configuration; a no-op on other platforms. Port of the C# extension
+ * method `UseWorker` -> a free function taking the builder first.
+ */
+function useWorker(app, configure) {
+    if (app instanceof WorkerApplicationBuilder) {
+        configure(app.workers);
+    }
+    return app;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Port of Benzene.SelfHost - the platform-neutral self-hosted worker model: register long-running
+ * workers against a `WorkerApplicationBuilder`, compose them, and dispatch polled work concurrently
+ * with per-key ordering via `BoundedConcurrentDispatcher`.
+ *
+ * The dispatcher's `System.Threading.Channels` usage is re-created in-package as `BoundedChannel` (Node
+ * has no BCL Channels). `Benzene.HostedService` (the .NET generic-host `IHostedService` adapter) has no
+ * direct JS counterpart - Node has no generic host - but its user-facing shorthand does: `BenzeneHost`
+ * here owns a worker process's start/stop lifecycle, so an entry point is
+ * `await BenzeneHost.runAsync(StartUp)`.
+ */
+export * from './BoundedChannel';
+export * from './BoundedConcurrentDispatcher';
+export * from './CompositeBenzeneWorker';
+export * from './IBenzeneWorkerStartup';
+export * from './BenzeneWorkerBuilder';
+export * from './WorkerApplicationBuilder';
+export * from './InlineSelfHostedStartUp';
+export * from './BenzeneHost';

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Port of Benzene.SelfHost - the platform-neutral self-hosted worker model: register long-running
+ * workers against a `WorkerApplicationBuilder`, compose them, and dispatch polled work concurrently
+ * with per-key ordering via `BoundedConcurrentDispatcher`.
+ *
+ * The dispatcher's `System.Threading.Channels` usage is re-created in-package as `BoundedChannel` (Node
+ * has no BCL Channels). `Benzene.HostedService` (the .NET generic-host `IHostedService` adapter) has no
+ * direct JS counterpart - Node has no generic host - but its user-facing shorthand does: `BenzeneHost`
+ * here owns a worker process's start/stop lifecycle, so an entry point is
+ * `await BenzeneHost.runAsync(StartUp)`.
+ */
+__exportStar(require("./BoundedChannel"), exports);
+__exportStar(require("./BoundedConcurrentDispatcher"), exports);
+__exportStar(require("./CompositeBenzeneWorker"), exports);
+__exportStar(require("./IBenzeneWorkerStartup"), exports);
+__exportStar(require("./BenzeneWorkerBuilder"), exports);
+__exportStar(require("./WorkerApplicationBuilder"), exports);
+__exportStar(require("./InlineSelfHostedStartUp"), exports);
+__exportStar(require("./BenzeneHost"), exports);

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@benzenejs/self-host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "TypeScript port of Benzene.SelfHost",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@benzenejs/abstractions": "0.1.0-beta.2",
+    "@benzenejs/abstractions-middleware": "0.1.0-beta.2",
+    "@benzenejs/core-message-handlers": "0.1.0-beta.2",
+    "@benzenejs/core-middleware": "0.1.0-beta.2",
+    "@benzenejs/dependencies": "0.1.0-beta.2"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.