@amqp-contract/core 0.24.0 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Core utilities for AMQP setup and management in amqp-contract.**
 
-[![CI](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml)
+[![CI](https://github.com/btravstack/amqp-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/btravstack/amqp-contract/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@amqp-contract/core.svg?logo=npm)](https://www.npmjs.com/package/@amqp-contract/core)
 [![npm downloads](https://img.shields.io/npm/dm/@amqp-contract/core.svg)](https://www.npmjs.com/package/@amqp-contract/core)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue?logo=typescript)](https://www.typescriptlang.org/)
@@ -10,7 +10,7 @@
 
 This package provides centralized functionality for establishing AMQP topology (exchanges, queues, and bindings) from contract definitions, and defines the `Logger` interface used across amqp-contract packages.
 
-📖 **[Full documentation →](https://btravers.github.io/amqp-contract)**
+📖 **[Full documentation →](https://btravstack.github.io/amqp-contract)**
 
 ## Installation
 
@@ -68,7 +68,7 @@ const amqpClient = new AmqpClient(contract, {
 await amqpClient.close();
 ```
 
-For advanced channel configuration options (custom setup, prefetch, publisher confirms), see the [Channel Configuration Guide](https://btravers.github.io/amqp-contract/guide/channel-configuration).
+For advanced channel configuration options (custom setup, prefetch, publisher confirms), see the [Channel Configuration Guide](https://btravstack.github.io/amqp-contract/guide/channel-configuration).
 
 ### Logger Interface
 
@@ -93,16 +93,16 @@ const client = (
     urls: ["amqp://localhost"],
     logger, // Optional: logs published messages
   })
-)._unsafeUnwrap();
+).unwrap();
 ```
 
 ## API
 
-For complete API documentation, see the [@amqp-contract/core API Reference](https://btravers.github.io/amqp-contract/api/core).
+For complete API documentation, see the [@amqp-contract/core API Reference](https://btravstack.github.io/amqp-contract/api/core).
 
 ## Documentation
 
-📖 **[Read the full documentation →](https://btravers.github.io/amqp-contract)**
+📖 **[Read the full documentation →](https://btravstack.github.io/amqp-contract)**
 
 ## License
 

package/dist/index.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-let neverthrow = require("neverthrow");
+let unthrown = require("unthrown");
 let amqp_connection_manager = require("amqp-connection-manager");
 amqp_connection_manager = __toESM(amqp_connection_manager, 1);
 let _amqp_contract_contract = require("@amqp-contract/contract");
@@ -184,33 +184,40 @@ function _resetConnectionsForTesting() {
 *
 * This includes AMQP connection failures, channel issues, validation failures,
 * and other runtime errors. This error is shared across core, worker, and client packages.
+*
+* Built on unthrown's {@link TaggedError}, so it carries a `_tag` of
+* `"@amqp-contract/TechnicalError"` for exhaustive dispatch via `matchTags`. The
+* tag is namespaced to avoid colliding with other libraries' tags in a shared
+* `matchTags`; the human-facing `Error.name` is kept bare (`"TechnicalError"`).
+* Remains a real `Error` (and a *modeled* error — it lives in the `E` channel of
+* a `Result`, never the `Defect` channel).
 */
-var TechnicalError = class extends Error {
+var TechnicalError = class extends (0, unthrown.TaggedError)("@amqp-contract/TechnicalError", { name: "TechnicalError" }) {
 	constructor(message, cause) {
-		super(message);
-		this.cause = cause;
-		this.name = "TechnicalError";
-		const ErrorConstructor = Error;
-		if (typeof ErrorConstructor.captureStackTrace === "function") ErrorConstructor.captureStackTrace(this, this.constructor);
+		super({
+			message,
+			cause
+		});
 	}
 };
 /**
 * Error thrown when message validation fails (payload or headers).
 *
 * Used by both the client (publish-time payload validation) and the worker
-* (consume-time payload and headers validation).
+* (consume-time payload and headers validation). Carries a `_tag` of
+* `"@amqp-contract/MessageValidationError"` (namespaced to avoid collisions);
+* the `Error.name` is kept bare (`"MessageValidationError"`).
 *
 * @param source - The name of the publisher or consumer that triggered the validation
 * @param issues - The validation issues from the Standard Schema validation
 */
-var MessageValidationError = class extends Error {
+var MessageValidationError = class extends (0, unthrown.TaggedError)("@amqp-contract/MessageValidationError", { name: "MessageValidationError" }) {
 	constructor(source, issues) {
-		super(`Message validation failed for "${source}"`);
-		this.source = source;
-		this.issues = issues;
-		this.name = "MessageValidationError";
-		const ErrorConstructor = Error;
-		if (typeof ErrorConstructor.captureStackTrace === "function") ErrorConstructor.captureStackTrace(this, this.constructor);
+		super({
+			message: `Message validation failed for "${source}"`,
+			source,
+			issues
+		});
 	}
 };
 //#endregion
@@ -238,10 +245,10 @@ var MessageValidationError = class extends Error {
 async function setupAmqpTopology(channel, contract) {
 	const exchanges = Object.values(contract.exchanges ?? {}).filter((e) => e.name !== "");
 	const exchangeErrors = (await Promise.allSettled(exchanges.map((exchange) => channel.assertExchange(exchange.name, exchange.type, {
-		durable: exchange.durable,
-		autoDelete: exchange.autoDelete,
-		internal: exchange.internal,
-		arguments: exchange.arguments
+		...exchange.durable !== void 0 && { durable: exchange.durable },
+		...exchange.autoDelete !== void 0 && { autoDelete: exchange.autoDelete },
+		...exchange.internal !== void 0 && { internal: exchange.internal },
+		...exchange.arguments !== void 0 && { arguments: exchange.arguments }
 	})))).map((result, i) => ({
 		result,
 		name: exchanges[i].name
@@ -272,9 +279,9 @@ async function setupAmqpTopology(channel, contract) {
 		});
 		if (queue.maxPriority !== void 0) queueArguments["x-max-priority"] = queue.maxPriority;
 		return channel.assertQueue(queue.name, {
-			durable: queue.durable,
-			exclusive: queue.exclusive,
-			autoDelete: queue.autoDelete,
+			...queue.durable !== void 0 && { durable: queue.durable },
+			...queue.exclusive !== void 0 && { exclusive: queue.exclusive },
+			...queue.autoDelete !== void 0 && { autoDelete: queue.autoDelete },
 			arguments: queueArguments
 		});
 	}))).map((result, i) => ({
@@ -348,7 +355,7 @@ function resolveConnectTimeoutMs(input) {
 * - Automatic AMQP topology setup (exchanges, queues, bindings) from contract
 * - Channel creation with JSON serialization enabled by default
 *
-* All operations return `ResultAsync<T, TechnicalError>` for consistent error handling.
+* All operations return `AsyncResult<T, TechnicalError>` for consistent error handling.
 *
 * @example
 * ```typescript
@@ -357,7 +364,7 @@ function resolveConnectTimeoutMs(input) {
 *   connectionOptions: { heartbeatIntervalInSeconds: 30 }
 * });
 *
-* // Wait for connection (ResultAsync is thenable)
+* // Wait for connection (AsyncResult is thenable)
 * await client.waitForConnect();
 *
 * // Publish a message
@@ -368,6 +375,7 @@ function resolveConnectTimeoutMs(input) {
 * ```
 */
 var AmqpClient = class {
+	contract;
 	connection;
 	channelWrapper;
 	urls;
@@ -375,6 +383,15 @@ var AmqpClient = class {
 	/** Resolved timeout in ms; `null` means "wait forever". */
 	connectTimeoutMs;
 	/**
+	* Per-consumer prefetch setup functions registered via `addSetup` so they
+	* can be removed in {@link cancel} once the consumer is gone — otherwise
+	* the channel wrapper would replay the cancelled consumer's QoS on every
+	* reconnect and silently apply it to subsequent consumers.
+	*
+	* @internal
+	*/
+	prefetchSetups = /* @__PURE__ */ new Map();
+	/**
 	* Create a new AMQP client instance.
 	*
 	* The client will automatically:
@@ -422,7 +439,7 @@ var AmqpClient = class {
 	* Wait for the channel to be connected and ready.
 	*
 	* If `connectTimeoutMs` was provided in the constructor options, the returned
-	* ResultAsync resolves to `err(TechnicalError)` once the timeout elapses.
+	* AsyncResult resolves to `err(TechnicalError)` once the timeout elapses.
 	* Without a timeout, this waits forever — amqp-connection-manager retries
 	* connections indefinitely and never errors on its own.
 	*
@@ -435,7 +452,7 @@ var AmqpClient = class {
 	waitForConnect() {
 		const connectPromise = this.channelWrapper.waitForConnect();
 		const timeoutMs = this.connectTimeoutMs;
-		const racedPromise = timeoutMs === null ? connectPromise : new Promise((resolve, reject) => {
+		return (0, unthrown.fromPromise)(timeoutMs === null ? connectPromise : new Promise((resolve, reject) => {
 			const handle = setTimeout(() => {
 				reject(/* @__PURE__ */ new Error(`Timed out waiting for AMQP connection after ${timeoutMs}ms`));
 			}, timeoutMs);
@@ -446,38 +463,75 @@ var AmqpClient = class {
 				clearTimeout(handle);
 				reject(error);
 			});
-		});
-		return neverthrow.ResultAsync.fromPromise(racedPromise, (error) => new TechnicalError("Failed to connect to AMQP broker", error));
+		}), (error) => new TechnicalError("Failed to connect to AMQP broker", error));
 	}
 	/**
 	* Publish a message to an exchange.
 	*
-	* @returns ResultAsync resolving to `true` if the message was sent, `false` if the channel buffer is full.
+	* @returns AsyncResult resolving to `true` if the message was sent, `false` if the channel buffer is full.
 	*/
 	publish(exchange, routingKey, content, options) {
-		return neverthrow.ResultAsync.fromPromise(this.channelWrapper.publish(exchange, routingKey, content, options), (error) => new TechnicalError("Failed to publish message", error));
+		return (0, unthrown.fromPromise)(this.channelWrapper.publish(exchange, routingKey, content, options), (error) => new TechnicalError("Failed to publish message", error));
 	}
 	/**
 	* Publish a message directly to a queue.
 	*
-	* @returns ResultAsync resolving to `true` if the message was sent, `false` if the channel buffer is full.
+	* @returns AsyncResult resolving to `true` if the message was sent, `false` if the channel buffer is full.
 	*/
 	sendToQueue(queue, content, options) {
-		return neverthrow.ResultAsync.fromPromise(this.channelWrapper.sendToQueue(queue, content, options), (error) => new TechnicalError("Failed to publish message to queue", error));
+		return (0, unthrown.fromPromise)(this.channelWrapper.sendToQueue(queue, content, options), (error) => new TechnicalError("Failed to publish message to queue", error));
 	}
 	/**
 	* Start consuming messages from a queue.
 	*
-	* @returns ResultAsync resolving to the consumer tag.
+	* If `options.prefetch` is set, a per-consumer prefetch count is applied via
+	* `channel.prefetch(count, false)` registered as a setup function on the
+	* channel wrapper *before* the underlying `consume` call. Registering it via
+	* `addSetup` ensures the prefetch is reapplied automatically on channel
+	* reconnect; using `global=false` scopes it to subsequent consumers on the
+	* channel (RabbitMQ semantics — opposite of intuition: `false` is per-
+	* consumer, `true` is channel-wide).
+	*
+	* `prefetch` is stripped from the options handed to `channelWrapper.consume`
+	* because it is not a valid `amqplib` `Options.Consume` field — leaving it
+	* in would just travel as a no-op key-value pair on the consume frame.
+	*
+	* @returns AsyncResult resolving to the consumer tag.
 	*/
 	consume(queue, callback, options) {
-		return neverthrow.ResultAsync.fromPromise(this.channelWrapper.consume(queue, callback, options), (error) => new TechnicalError("Failed to start consuming messages", error)).map((reply) => reply.consumerTag);
+		const { prefetch, ...consumeOptions } = options ?? {};
+		if (prefetch !== void 0) {
+			if (!Number.isInteger(prefetch) || prefetch < 0 || prefetch > 65535) return (0, unthrown.err)(new TechnicalError(`Invalid prefetch: expected a non-negative integer ≤ 65535, got ${String(prefetch)}`)).toAsync();
+		}
+		const prefetchSetup = typeof prefetch === "number" ? async (channel) => {
+			await channel.prefetch(prefetch, false);
+		} : void 0;
+		return (0, unthrown.fromPromise)((async () => {
+			if (prefetchSetup) await this.channelWrapper.addSetup(prefetchSetup);
+			let reply;
+			try {
+				reply = await this.channelWrapper.consume(queue, callback, consumeOptions);
+			} catch (error) {
+				if (prefetchSetup) await this.channelWrapper.removeSetup(prefetchSetup).catch(() => {});
+				throw error;
+			}
+			if (prefetchSetup) this.prefetchSetups.set(reply.consumerTag, prefetchSetup);
+			return reply;
+		})(), (error) => new TechnicalError("Failed to start consuming messages", error)).map((reply) => reply.consumerTag);
 	}
 	/**
 	* Cancel a consumer by its consumer tag.
 	*/
 	cancel(consumerTag) {
-		return neverthrow.ResultAsync.fromPromise(this.channelWrapper.cancel(consumerTag), (error) => new TechnicalError("Failed to cancel consumer", error)).map(() => void 0);
+		return (0, unthrown.fromPromise)((async () => {
+			const setup = this.prefetchSetups.get(consumerTag);
+			this.prefetchSetups.delete(consumerTag);
+			try {
+				await this.channelWrapper.cancel(consumerTag);
+			} finally {
+				if (setup !== void 0) await this.channelWrapper.removeSetup(setup).catch(() => {});
+			}
+		})(), (error) => new TechnicalError("Failed to cancel consumer", error)).map(() => void 0);
 	}
 	/**
 	* Acknowledge a message.
@@ -534,14 +588,14 @@ var AmqpClient = class {
 	* errors are wrapped in an AggregateError.
 	*/
 	close() {
-		return new neverthrow.ResultAsync((async () => {
-			const channelResult = await neverthrow.ResultAsync.fromPromise(this.channelWrapper.close(), (error) => new TechnicalError("Failed to close channel", error));
-			const releaseResult = await neverthrow.ResultAsync.fromPromise(ConnectionManagerSingleton.getInstance().releaseConnection(this.urls, this.connectionOptions), (error) => new TechnicalError("Failed to release connection", error));
-			if (channelResult.isErr() && releaseResult.isErr()) return (0, neverthrow.err)(new TechnicalError("Failed to close channel and release connection", new AggregateError([channelResult.error, releaseResult.error], "Failed to close channel and release connection")));
+		return (0, unthrown.fromSafePromise)((async () => {
+			const channelResult = await (0, unthrown.fromPromise)(this.channelWrapper.close(), (error) => new TechnicalError("Failed to close channel", error));
+			const releaseResult = await (0, unthrown.fromPromise)(ConnectionManagerSingleton.getInstance().releaseConnection(this.urls, this.connectionOptions), (error) => new TechnicalError("Failed to release connection", error));
+			if (channelResult.isErr() && releaseResult.isErr()) return (0, unthrown.err)(new TechnicalError("Failed to close channel and release connection", new AggregateError([channelResult.error, releaseResult.error], "Failed to close channel and release connection")));
 			if (channelResult.isErr()) return channelResult;
 			if (releaseResult.isErr()) return releaseResult;
-			return (0, neverthrow.ok)(void 0);
-		})());
+			return (0, unthrown.ok)(void 0);
+		})()).flatMap((result) => result);
 	}
 	/**
 	* Reset connection singleton cache (for testing only)
@@ -552,6 +606,32 @@ var AmqpClient = class {
 	}
 };
 //#endregion
+//#region src/parsing.ts
+/**
+* Parse a `Buffer` as JSON, mapping any `JSON.parse` exception to the
+* caller-supplied error type.
+*
+* Use this in consume / reply paths where a parse failure is a typed value,
+* not a thrown exception — the caller decides how to translate the raw error
+* into a domain-level error (e.g. {@link TechnicalError}).
+*
+* @typeParam E - The error type produced by `errorFn`.
+* @param buffer - The raw message body to parse.
+* @param errorFn - Callback invoked with the underlying `JSON.parse` error.
+* @returns A `Result` containing the parsed `unknown` value or the mapped error.
+*
+* @example
+* ```typescript
+* const parsed = safeJsonParse(
+*   msg.content,
+*   (error) => new TechnicalError("Failed to parse JSON", error),
+* );
+* ```
+*/
+function safeJsonParse(buffer, errorFn) {
+	return (0, unthrown.fromThrowable)(() => JSON.parse(buffer.toString()), errorFn)();
+}
+//#endregion
 //#region src/telemetry.ts
 /**
 * SpanKind values from OpenTelemetry.
@@ -830,6 +910,7 @@ exports.endSpanSuccess = endSpanSuccess;
 exports.recordConsumeMetric = recordConsumeMetric;
 exports.recordLateRpcReply = recordLateRpcReply;
 exports.recordPublishMetric = recordPublishMetric;
+exports.safeJsonParse = safeJsonParse;
 exports.setupAmqpTopology = setupAmqpTopology;
 exports.startConsumeSpan = startConsumeSpan;
 exports.startPublishSpan = startPublishSpan;

package/dist/index.d.cts

@@ -1,32 +1,47 @@
 import { ContractDefinition } from "@amqp-contract/contract";
 import { AmqpConnectionManager, AmqpConnectionManagerOptions, ConnectionUrl, CreateChannelOpts } from "amqp-connection-manager";
 import { Channel, ConsumeMessage, Options } from "amqplib";
-import { ResultAsync } from "neverthrow";
+import { AsyncResult, Result } from "unthrown";
 import { Attributes, Counter, Histogram, Span, Tracer } from "@opentelemetry/api";
 
 //#region src/errors.d.ts
+declare const TechnicalError_base: import("unthrown").TaggedErrorConstructor<"@amqp-contract/TechnicalError">;
 /**
  * Error for technical/runtime failures that cannot be prevented by TypeScript.
  *
  * This includes AMQP connection failures, channel issues, validation failures,
  * and other runtime errors. This error is shared across core, worker, and client packages.
+ *
+ * Built on unthrown's {@link TaggedError}, so it carries a `_tag` of
+ * `"@amqp-contract/TechnicalError"` for exhaustive dispatch via `matchTags`. The
+ * tag is namespaced to avoid colliding with other libraries' tags in a shared
+ * `matchTags`; the human-facing `Error.name` is kept bare (`"TechnicalError"`).
+ * Remains a real `Error` (and a *modeled* error — it lives in the `E` channel of
+ * a `Result`, never the `Defect` channel).
  */
-declare class TechnicalError extends Error {
-  readonly cause?: unknown | undefined;
-  constructor(message: string, cause?: unknown | undefined);
+declare class TechnicalError extends TechnicalError_base<{
+  message: string;
+  cause?: unknown;
+}> {
+  constructor(message: string, cause?: unknown);
 }
+declare const MessageValidationError_base: import("unthrown").TaggedErrorConstructor<"@amqp-contract/MessageValidationError">;
 /**
  * Error thrown when message validation fails (payload or headers).
  *
  * Used by both the client (publish-time payload validation) and the worker
- * (consume-time payload and headers validation).
+ * (consume-time payload and headers validation). Carries a `_tag` of
+ * `"@amqp-contract/MessageValidationError"` (namespaced to avoid collisions);
+ * the `Error.name` is kept bare (`"MessageValidationError"`).
  *
  * @param source - The name of the publisher or consumer that triggered the validation
  * @param issues - The validation issues from the Standard Schema validation
  */
-declare class MessageValidationError extends Error {
-  readonly source: string;
-  readonly issues: unknown;
+declare class MessageValidationError extends MessageValidationError_base<{
+  message: string;
+  source: string;
+  issues: unknown;
+}> {
   constructor(source: string, issues: unknown);
 }
 //#endregion
@@ -63,16 +78,29 @@ type AmqpClientOptions = {
  */
 type ConsumeCallback = (msg: ConsumeMessage | null) => void | Promise<void>;
 /**
- * Publish options that extend amqplib's Options.Publish with optional timeout support.
+ * Publish options for `AmqpClient.publish` / `AmqpClient.sendToQueue`.
+ *
+ * Currently a re-export of amqplib's `Options.Publish`. A previous version of
+ * this type also exposed a `timeout` field, but that field never had a
+ * meaningful AMQP-level effect in this codebase and has been removed to avoid
+ * suggesting behaviour we do not provide. (`amqp-connection-manager`'s own
+ * `publishTimeout` channel option is unrelated and is configured at channel
+ * creation, not per-publish.)
  */
-type PublishOptions = Options.Publish & {
-  /** Message will be rejected after timeout ms */timeout?: number;
-};
+type PublishOptions = Options.Publish;
 /**
- * Consume options that extend amqplib's Options.Consume with optional prefetch support.
+ * Consume options that extend amqplib's `Options.Consume` with an optional
+ * per-consumer prefetch count.
+ *
+ * `prefetch` is intercepted by {@link AmqpClient.consume}: it is stripped from
+ * the options handed to the underlying `channelWrapper.consume(...)` call
+ * (since amqplib's `Options.Consume` does not include it) and applied via
+ * `channel.prefetch(count, false)` registered through `addSetup` *before* the
+ * consume so the value is in effect when the consumer starts and is reapplied
+ * automatically on channel reconnect.
  */
 type ConsumerOptions = Options.Consume & {
-  /** Number of messages to prefetch */prefetch?: number;
+  /** Per-consumer prefetch count. Applied before `channel.consume(...)`. */prefetch?: number;
 };
 /**
  * AMQP client that manages connections and channels with automatic topology setup.
@@ -83,7 +111,7 @@ type ConsumerOptions = Options.Consume & {
  * - Automatic AMQP topology setup (exchanges, queues, bindings) from contract
  * - Channel creation with JSON serialization enabled by default
  *
- * All operations return `ResultAsync<T, TechnicalError>` for consistent error handling.
+ * All operations return `AsyncResult<T, TechnicalError>` for consistent error handling.
  *
  * @example
  * ```typescript
@@ -92,7 +120,7 @@ type ConsumerOptions = Options.Consume & {
  *   connectionOptions: { heartbeatIntervalInSeconds: 30 }
  * });
  *
- * // Wait for connection (ResultAsync is thenable)
+ * // Wait for connection (AsyncResult is thenable)
  * await client.waitForConnect();
  *
  * // Publish a message
@@ -110,6 +138,15 @@ declare class AmqpClient {
   private readonly connectionOptions?;
   /** Resolved timeout in ms; `null` means "wait forever". */
   private readonly connectTimeoutMs;
+  /**
+   * Per-consumer prefetch setup functions registered via `addSetup` so they
+   * can be removed in {@link cancel} once the consumer is gone — otherwise
+   * the channel wrapper would replay the cancelled consumer's QoS on every
+   * reconnect and silently apply it to subsequent consumers.
+   *
+   * @internal
+   */
+  private readonly prefetchSetups;
   /**
    * Create a new AMQP client instance.
    *
@@ -136,7 +173,7 @@ declare class AmqpClient {
    * Wait for the channel to be connected and ready.
    *
    * If `connectTimeoutMs` was provided in the constructor options, the returned
-   * ResultAsync resolves to `err(TechnicalError)` once the timeout elapses.
+   * AsyncResult resolves to `err(TechnicalError)` once the timeout elapses.
    * Without a timeout, this waits forever — amqp-connection-manager retries
    * connections indefinitely and never errors on its own.
    *
@@ -146,29 +183,41 @@ declare class AmqpClient {
    * path to release the connection — `waitForConnect` does not do this
    * automatically. The typed factories handle this cleanup for you.
    */
-  waitForConnect(): ResultAsync<void, TechnicalError>;
+  waitForConnect(): AsyncResult<void, TechnicalError>;
   /**
    * Publish a message to an exchange.
    *
-   * @returns ResultAsync resolving to `true` if the message was sent, `false` if the channel buffer is full.
+   * @returns AsyncResult resolving to `true` if the message was sent, `false` if the channel buffer is full.
    */
-  publish(exchange: string, routingKey: string, content: Buffer | unknown, options?: PublishOptions): ResultAsync<boolean, TechnicalError>;
+  publish(exchange: string, routingKey: string, content: Buffer | unknown, options?: PublishOptions): AsyncResult<boolean, TechnicalError>;
   /**
    * Publish a message directly to a queue.
    *
-   * @returns ResultAsync resolving to `true` if the message was sent, `false` if the channel buffer is full.
+   * @returns AsyncResult resolving to `true` if the message was sent, `false` if the channel buffer is full.
    */
-  sendToQueue(queue: string, content: Buffer | unknown, options?: PublishOptions): ResultAsync<boolean, TechnicalError>;
+  sendToQueue(queue: string, content: Buffer | unknown, options?: PublishOptions): AsyncResult<boolean, TechnicalError>;
   /**
    * Start consuming messages from a queue.
    *
-   * @returns ResultAsync resolving to the consumer tag.
+   * If `options.prefetch` is set, a per-consumer prefetch count is applied via
+   * `channel.prefetch(count, false)` registered as a setup function on the
+   * channel wrapper *before* the underlying `consume` call. Registering it via
+   * `addSetup` ensures the prefetch is reapplied automatically on channel
+   * reconnect; using `global=false` scopes it to subsequent consumers on the
+   * channel (RabbitMQ semantics — opposite of intuition: `false` is per-
+   * consumer, `true` is channel-wide).
+   *
+   * `prefetch` is stripped from the options handed to `channelWrapper.consume`
+   * because it is not a valid `amqplib` `Options.Consume` field — leaving it
+   * in would just travel as a no-op key-value pair on the consume frame.
+   *
+   * @returns AsyncResult resolving to the consumer tag.
    */
-  consume(queue: string, callback: ConsumeCallback, options?: ConsumerOptions): ResultAsync<string, TechnicalError>;
+  consume(queue: string, callback: ConsumeCallback, options?: ConsumerOptions): AsyncResult<string, TechnicalError>;
   /**
    * Cancel a consumer by its consumer tag.
    */
-  cancel(consumerTag: string): ResultAsync<void, TechnicalError>;
+  cancel(consumerTag: string): AsyncResult<void, TechnicalError>;
   /**
    * Acknowledge a message.
    *
@@ -215,7 +264,7 @@ declare class AmqpClient {
    * Both steps run regardless of each other's outcome; if both fail, the
    * errors are wrapped in an AggregateError.
    */
-  close(): ResultAsync<void, TechnicalError>;
+  close(): AsyncResult<void, TechnicalError>;
   /**
    * Reset connection singleton cache (for testing only)
    * @internal
@@ -296,6 +345,30 @@ type Logger = {
   error(message: string, context?: LoggerContext): void;
 };
 //#endregion
+//#region src/parsing.d.ts
+/**
+ * Parse a `Buffer` as JSON, mapping any `JSON.parse` exception to the
+ * caller-supplied error type.
+ *
+ * Use this in consume / reply paths where a parse failure is a typed value,
+ * not a thrown exception — the caller decides how to translate the raw error
+ * into a domain-level error (e.g. {@link TechnicalError}).
+ *
+ * @typeParam E - The error type produced by `errorFn`.
+ * @param buffer - The raw message body to parse.
+ * @param errorFn - Callback invoked with the underlying `JSON.parse` error.
+ * @returns A `Result` containing the parsed `unknown` value or the mapped error.
+ *
+ * @example
+ * ```typescript
+ * const parsed = safeJsonParse(
+ *   msg.content,
+ *   (error) => new TechnicalError("Failed to parse JSON", error),
+ * );
+ * ```
+ */
+declare function safeJsonParse<E>(buffer: Buffer, errorFn: (raw: unknown) => E): Result<unknown, E>;
+//#endregion
 //#region src/setup.d.ts
 /**
  * Setup AMQP topology (exchanges, queues, and bindings) from a contract definition.
@@ -423,5 +496,5 @@ declare function recordLateRpcReply(provider: TelemetryProvider, reason: "unknow
  */
 declare function _resetTelemetryCacheForTesting(): void;
 //#endregion
-export { AmqpClient, type AmqpClientOptions, type ConsumeCallback, type ConsumerOptions, DEFAULT_CONNECT_TIMEOUT_MS, type Logger, type LoggerContext, MessageValidationError, MessagingSemanticConventions, type PublishOptions, TechnicalError, type TelemetryProvider, _getConnectionCountForTesting, _resetConnectionsForTesting, _resetTelemetryCacheForTesting, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, recordLateRpcReply, recordPublishMetric, setupAmqpTopology, startConsumeSpan, startPublishSpan };
+export { AmqpClient, type AmqpClientOptions, type ConsumeCallback, type ConsumerOptions, DEFAULT_CONNECT_TIMEOUT_MS, type Logger, type LoggerContext, MessageValidationError, MessagingSemanticConventions, type PublishOptions, TechnicalError, type TelemetryProvider, _getConnectionCountForTesting, _resetConnectionsForTesting, _resetTelemetryCacheForTesting, defaultTelemetryProvider, endSpanError, endSpanSuccess, recordConsumeMetric, recordLateRpcReply, recordPublishMetric, safeJsonParse, setupAmqpTopology, startConsumeSpan, startPublishSpan };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts","../src/amqp-client.ts","../src/connection-manager.ts","../src/logger.ts","../src/setup.ts","../src/telemetry.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts","../src/amqp-client.ts","../src/connection-manager.ts","../src/logger.ts","../src/parsing.ts","../src/setup.ts","../src/telemetry.ts"],"mappings":"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"}