@btravstack/amqp-worker 0.6.0 → 0.8.0

package/README.md

@@ -115,14 +115,14 @@ module lists (`imports`, `provides`, `exports`, `needs`). The `amqp()`
 primitive does not take `handlers` as an option — it **needs** the handlers
 provider on its own port, which is how the composition root supplies it:
 
-| Option                   | What it is                                                                                                      |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `contract`               | the `amqp-contract` contract; the queues consumed are read off it                                               |
-| `handlers`               | the handlers provider — what `AmqpHandlers(contract)(...)` returns for this contract                            |
-| `url`                    | pins the broker instead of reading `AMQP_URL` (default `amqp://127.0.0.1:5672`) — a test's container            |
-| `connectionOptions`      | `AmqpConnectionOptions`, the library's own connection tuning: heartbeat, reconnect interval, `findServers`, TLS |
-| `defaultConsumerOptions` | the library's `ConsumerOptions`, applied to every handler: `prefetch` (the throughput knob), `priority`, …      |
-| `connectTimeoutMs`       | how long startup waits before an unreachable broker is a `RuntimeStartFailed` (the library defaults to 30 s)    |
+| Option                   | What it is                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `contract`               | the `amqp-contract` contract; the queues consumed are read off it                                                               |
+| `handlers`               | the handlers provider — what `AmqpHandlers(contract)(...)` returns for this contract                                            |
+| `url`                    | pins `AMQP_URL` (default `amqp://127.0.0.1:5672`) — a test's container                                                          |
+| `connectionOptions`      | `AmqpConnectionOptions`, the library's own connection tuning: heartbeat, reconnect interval, `findServers`, TLS                 |
+| `defaultConsumerOptions` | the library's `ConsumerOptions`, applied to every handler: `prefetch` (the throughput knob), `priority`, …                      |
+| `connectTimeoutMs`       | pins `AMQP_CONNECT_TIMEOUT_MS` — how long startup waits before an unreachable broker is a `RuntimeStartFailed` (default `5000`) |
 
 The full table — required/optional, defaults, and the reasoning — lives on
 [the reference page](https://btravstack.github.io/btravstack/reference/amqp-worker),

package/dist/index.cjs

@@ -75,10 +75,17 @@ const traceIdOfTraceparent = (header) => {
 //#region src/amqp-runtime.ts
 /**
 * The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
-* `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
-* read it — a publisher sharing the consumer's broker, say.
+* `amqp://127.0.0.1:5672`) and `AMQP_CONNECT_TIMEOUT_MS` (default `5_000`)
+* unless pinned, and anything else in the graph may read it — a publisher
+* sharing the consumer's broker, say.
 */
 var AmqpConfig = class extends (0, _btravstack_di.Port)("AmqpConfig") {};
+/**
+* Five seconds. The library's own default is 30, which is longer than most
+* orchestrators wait before restarting the pod — an unreachable broker should
+* be reported, not sat on.
+*/
+const DEFAULT_CONNECT_TIMEOUT_MS = 5e3;
 /** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
 var AmqpRuntime = class extends _btravstack_core.RuntimePort {};
 /**
@@ -99,7 +106,13 @@ const AmqpHandlersPort = (0, _btravstack_di.Port)("AmqpHandlers");
 * With `url` pinned the module reads nothing from the environment.
 */
 const amqp = (options) => {
-	const config = options.url === void 0 ? _btravstack_config.Config.provider(AmqpConfig)(_btravstack_config.Config.object({ url: _btravstack_config.Config.string("AMQP_URL", { default: "amqp://127.0.0.1:5672" }) })) : (0, _btravstack_di.Provider)(AmqpConfig)({ value: { url: options.url } });
+	const config = _btravstack_config.Config.provider(AmqpConfig)(_btravstack_config.Config.object({
+		url: _btravstack_config.Config.pinned(options.url, _btravstack_config.Config.string("AMQP_URL", { default: "amqp://127.0.0.1:5672" })),
+		connectTimeoutMs: _btravstack_config.Config.pinned(options.connectTimeoutMs, _btravstack_config.Config.integer("AMQP_CONNECT_TIMEOUT_MS", {
+			default: DEFAULT_CONNECT_TIMEOUT_MS,
+			min: 0
+		}))
+	}));
 	return (0, _btravstack_di.Module)("Amqp")({
 		needs: [_btravstack_config.Env, AmqpHandlersPort],
 		provides: [config, (0, _btravstack_di.Provider)(AmqpRuntime)({
@@ -153,7 +166,7 @@ const createWorker = (host, config, options, handlers) => _amqp_contract_worker.
 	urls: [config.url],
 	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
 	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
-	...options.connectTimeoutMs === void 0 ? {} : { connectTimeoutMs: options.connectTimeoutMs }
+	connectTimeoutMs: config.connectTimeoutMs
 }).map((worker) => consume(worker, queuesOf(options.contract))).recoverDefect((cause) => (0, unthrown.ErrAsync)(startFailed(cause)));
 const consume = (worker, queues) => {
 	let closing;
@@ -188,17 +201,11 @@ const consume = (worker, queues) => {
 * ```
 */
 const AmqpModule = (name) => (options) => {
-	const { contract, handlers, url, connectionOptions, defaultConsumerOptions, connectTimeoutMs } = options;
+	const { handlers } = options;
 	const imports = options.imports ?? [];
 	const provides = options.provides ?? [];
 	const exports = options.exports ?? [];
-	const starter = amqp({
-		contract,
-		...url === void 0 ? {} : { url },
-		...connectionOptions === void 0 ? {} : { connectionOptions },
-		...defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions },
-		...connectTimeoutMs === void 0 ? {} : { connectTimeoutMs }
-	});
+	const starter = amqp(options);
 	return (0, _btravstack_di.Module)(name)({
 		imports: [...imports, starter],
 		provides: [handlers, ...provides],

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
 import { ConfigInvalid, Env } from "@btravstack/config";
 import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider } from "@btravstack/di";
+import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
 import { Runtime, RuntimePort } from "@btravstack/core";
 //#region src/handler.d.ts
 /** The consumer and rpc names `C` declares — the keys of its handlers record. */
@@ -33,11 +33,14 @@ type AmqpInfo = {
 declare const AmqpConfig_base: import("@btravstack/di").PortClass<"AmqpConfig">;
 /**
  * The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
- * `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
- * read it — a publisher sharing the consumer's broker, say.
+ * `amqp://127.0.0.1:5672`) and `AMQP_CONNECT_TIMEOUT_MS` (default `5_000`)
+ * unless pinned, and anything else in the graph may read it — a publisher
+ * sharing the consumer's broker, say.
  */
 declare class AmqpConfig extends AmqpConfig_base<{
   readonly url: string;
+  /** How long `create` waits for the connection before failing. */
+  readonly connectTimeoutMs: number;
 }> {}
 /** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
 declare class AmqpRuntime extends RuntimePort<Runtime<never, AmqpInfo>> {}
@@ -64,17 +67,25 @@ type AmqpOptions<TContract extends AnyAmqpContract> = {
    * built by di from the services it declares.
    */
   readonly contract: TContract;
-  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
+} & AmqpTuning;
+/**
+ * What an AMQP deployment tunes, shared verbatim by `amqp()` and `AmqpModule` —
+ * spelled once so the two cannot drift, which is what a second copy of an
+ * option list always eventually does.
+ */
+type AmqpTuning = {
+  /** Pins `AmqpConfig.url` instead of reading `AMQP_URL` — a test's container. */
   readonly url?: string;
   /** Connection tuning, `@amqp-contract/worker`'s own type: heartbeat, reconnect interval, `findServers`, TLS/socket options. */
   readonly connectionOptions?: AmqpConnectionOptions;
   /** Consumer defaults applied to every handler, the library's own type: `prefetch`, `priority`, `arguments`, `consumerTag`, `exclusive`. */
   readonly defaultConsumerOptions?: ConsumerOptions;
   /**
-   * How long `create` waits for the connection before failing. Passed straight
-   * through — it is a top-level `CreateWorkerOptions` field, NOT nested under
-   * `connectionOptions`, where setting it is silently inert. Without it an
-   * unreachable broker takes the library's 30s default to report.
+   * Pins `AmqpConfig.connectTimeoutMs` instead of reading
+   * `AMQP_CONNECT_TIMEOUT_MS` (default {@link DEFAULT_CONNECT_TIMEOUT_MS}) —
+   * how long `create` waits for the connection before failing. Passed straight
+   * through as a top-level `CreateWorkerOptions` field, NOT nested under
+   * `connectionOptions`, where setting it is silently inert.
    */
   readonly connectTimeoutMs?: number;
 };
@@ -135,18 +146,10 @@ type AmqpStarter<TContract extends AnyAmqpContract> = Module<AmqpRuntime | AmqpC
 type Imports<I extends readonly AnyModule[], TContract extends AnyAmqpContract> = readonly [...I, AmqpStarter<TContract>];
 /** The handlers provider plus the application's own — the tuple `Module(name)` is handed. */
 type Provides<P extends readonly AnyProvider[], TContract extends AnyAmqpContract, HandlersError, HandlersNeeds> = readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P];
-type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = {
+type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = AmqpTuning & {
   readonly contract: TContract;
   /** The application's handlers — what `AmqpHandlers(contract)(…)` returns for THIS contract. */
   readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>;
-  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
-  readonly url?: string;
-  /** See `AmqpOptions.connectionOptions`. */
-  readonly connectionOptions?: AmqpConnectionOptions;
-  /** See `AmqpOptions.defaultConsumerOptions`. */
-  readonly defaultConsumerOptions?: ConsumerOptions;
-  /** See `AmqpOptions.connectTimeoutMs`. */
-  readonly connectTimeoutMs?: number;
   readonly imports?: I;
   readonly provides?: P;
   /** The application's own exports; `AmqpRuntime` is added, since `start` resolves it. */

package/dist/index.d.mts

@@ -33,11 +33,14 @@ type AmqpInfo = {
 declare const AmqpConfig_base: import("@btravstack/di").PortClass<"AmqpConfig">;
 /**
  * The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
- * `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
- * read it — a publisher sharing the consumer's broker, say.
+ * `amqp://127.0.0.1:5672`) and `AMQP_CONNECT_TIMEOUT_MS` (default `5_000`)
+ * unless pinned, and anything else in the graph may read it — a publisher
+ * sharing the consumer's broker, say.
  */
 declare class AmqpConfig extends AmqpConfig_base<{
   readonly url: string;
+  /** How long `create` waits for the connection before failing. */
+  readonly connectTimeoutMs: number;
 }> {}
 /** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
 declare class AmqpRuntime extends RuntimePort<Runtime<never, AmqpInfo>> {}
@@ -64,17 +67,25 @@ type AmqpOptions<TContract extends AnyAmqpContract> = {
    * built by di from the services it declares.
    */
   readonly contract: TContract;
-  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
+} & AmqpTuning;
+/**
+ * What an AMQP deployment tunes, shared verbatim by `amqp()` and `AmqpModule` —
+ * spelled once so the two cannot drift, which is what a second copy of an
+ * option list always eventually does.
+ */
+type AmqpTuning = {
+  /** Pins `AmqpConfig.url` instead of reading `AMQP_URL` — a test's container. */
   readonly url?: string;
   /** Connection tuning, `@amqp-contract/worker`'s own type: heartbeat, reconnect interval, `findServers`, TLS/socket options. */
   readonly connectionOptions?: AmqpConnectionOptions;
   /** Consumer defaults applied to every handler, the library's own type: `prefetch`, `priority`, `arguments`, `consumerTag`, `exclusive`. */
   readonly defaultConsumerOptions?: ConsumerOptions;
   /**
-   * How long `create` waits for the connection before failing. Passed straight
-   * through — it is a top-level `CreateWorkerOptions` field, NOT nested under
-   * `connectionOptions`, where setting it is silently inert. Without it an
-   * unreachable broker takes the library's 30s default to report.
+   * Pins `AmqpConfig.connectTimeoutMs` instead of reading
+   * `AMQP_CONNECT_TIMEOUT_MS` (default {@link DEFAULT_CONNECT_TIMEOUT_MS}) —
+   * how long `create` waits for the connection before failing. Passed straight
+   * through as a top-level `CreateWorkerOptions` field, NOT nested under
+   * `connectionOptions`, where setting it is silently inert.
    */
   readonly connectTimeoutMs?: number;
 };
@@ -135,18 +146,10 @@ type AmqpStarter<TContract extends AnyAmqpContract> = Module<AmqpRuntime | AmqpC
 type Imports<I extends readonly AnyModule[], TContract extends AnyAmqpContract> = readonly [...I, AmqpStarter<TContract>];
 /** The handlers provider plus the application's own — the tuple `Module(name)` is handed. */
 type Provides<P extends readonly AnyProvider[], TContract extends AnyAmqpContract, HandlersError, HandlersNeeds> = readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P];
-type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = {
+type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = AmqpTuning & {
   readonly contract: TContract;
   /** The application's handlers — what `AmqpHandlers(contract)(…)` returns for THIS contract. */
   readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>;
-  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
-  readonly url?: string;
-  /** See `AmqpOptions.connectionOptions`. */
-  readonly connectionOptions?: AmqpConnectionOptions;
-  /** See `AmqpOptions.defaultConsumerOptions`. */
-  readonly defaultConsumerOptions?: ConsumerOptions;
-  /** See `AmqpOptions.connectTimeoutMs`. */
-  readonly connectTimeoutMs?: number;
   readonly imports?: I;
   readonly provides?: P;
   /** The application's own exports; `AmqpRuntime` is added, since `start` resolves it. */

package/dist/index.mjs

@@ -74,10 +74,17 @@ const traceIdOfTraceparent = (header) => {
 //#region src/amqp-runtime.ts
 /**
 * The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
-* `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
-* read it — a publisher sharing the consumer's broker, say.
+* `amqp://127.0.0.1:5672`) and `AMQP_CONNECT_TIMEOUT_MS` (default `5_000`)
+* unless pinned, and anything else in the graph may read it — a publisher
+* sharing the consumer's broker, say.
 */
 var AmqpConfig = class extends Port("AmqpConfig") {};
+/**
+* Five seconds. The library's own default is 30, which is longer than most
+* orchestrators wait before restarting the pod — an unreachable broker should
+* be reported, not sat on.
+*/
+const DEFAULT_CONNECT_TIMEOUT_MS = 5e3;
 /** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
 var AmqpRuntime = class extends RuntimePort {};
 /**
@@ -98,7 +105,13 @@ const AmqpHandlersPort = Port("AmqpHandlers");
 * With `url` pinned the module reads nothing from the environment.
 */
 const amqp = (options) => {
-	const config = options.url === void 0 ? Config.provider(AmqpConfig)(Config.object({ url: Config.string("AMQP_URL", { default: "amqp://127.0.0.1:5672" }) })) : Provider(AmqpConfig)({ value: { url: options.url } });
+	const config = Config.provider(AmqpConfig)(Config.object({
+		url: Config.pinned(options.url, Config.string("AMQP_URL", { default: "amqp://127.0.0.1:5672" })),
+		connectTimeoutMs: Config.pinned(options.connectTimeoutMs, Config.integer("AMQP_CONNECT_TIMEOUT_MS", {
+			default: DEFAULT_CONNECT_TIMEOUT_MS,
+			min: 0
+		}))
+	}));
 	return Module("Amqp")({
 		needs: [Env, AmqpHandlersPort],
 		provides: [config, Provider(AmqpRuntime)({
@@ -152,7 +165,7 @@ const createWorker = (host, config, options, handlers) => TypedAmqpWorker.create
 	urls: [config.url],
 	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
 	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
-	...options.connectTimeoutMs === void 0 ? {} : { connectTimeoutMs: options.connectTimeoutMs }
+	connectTimeoutMs: config.connectTimeoutMs
 }).map((worker) => consume(worker, queuesOf(options.contract))).recoverDefect((cause) => ErrAsync(startFailed(cause)));
 const consume = (worker, queues) => {
 	let closing;
@@ -187,17 +200,11 @@ const consume = (worker, queues) => {
 * ```
 */
 const AmqpModule = (name) => (options) => {
-	const { contract, handlers, url, connectionOptions, defaultConsumerOptions, connectTimeoutMs } = options;
+	const { handlers } = options;
 	const imports = options.imports ?? [];
 	const provides = options.provides ?? [];
 	const exports = options.exports ?? [];
-	const starter = amqp({
-		contract,
-		...url === void 0 ? {} : { url },
-		...connectionOptions === void 0 ? {} : { connectionOptions },
-		...defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions },
-		...connectTimeoutMs === void 0 ? {} : { connectTimeoutMs }
-	});
+	const starter = amqp(options);
 	return Module(name)({
 		imports: [...imports, starter],
 		provides: [handlers, ...provides],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/amqp-worker",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The AMQP starter for @btravstack/core: the handlers as a port, one unit per delivery, and a drain the kernel's deadline releases",
   "keywords": [
     "amqp",
@@ -49,27 +49,27 @@
     "@amqp-contract/worker": "3.0.0-beta.6",
     "@btravstack/tsconfig": "0.2.0",
     "@opentelemetry/api": "1.9.1",
-    "@types/node": "26.2.0",
+    "@types/node": "26.4.0",
     "@unthrown/vitest": "5.7.0",
     "@vitest/coverage-v8": "4.1.11",
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "zod": "4.4.3",
-    "@btravstack/config": "0.6.0",
-    "@btravstack/core": "0.6.0",
-    "@btravstack/di": "0.6.0",
+    "zod": "4.5.1",
+    "@btravstack/config": "0.8.0",
+    "@btravstack/core": "0.8.0",
+    "@btravstack/di": "0.8.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/testing": "0.6.0"
+    "@btravstack/testing": "0.8.0"
   },
   "peerDependencies": {
     "@amqp-contract/worker": "^3.0.0-beta.6",
     "@opentelemetry/api": "^1",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.6.0",
-    "@btravstack/core": "^0.6.0",
-    "@btravstack/di": "^0.6.0"
+    "@btravstack/config": "^0.8.0",
+    "@btravstack/core": "^0.8.0",
+    "@btravstack/di": "^0.8.0"
   },
   "engines": {
     "node": ">=22"