hide-a-bed 6.0.0 → 7.0.0-beta.0

package/dist/esm/index.mjs

@@ -1,6 +1,6 @@
 import z, { z as z$1 } from "zod";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import needle from "needle";
+import { Readable } from "node:stream";
 import Chain from "stream-chain";
 import Parser from "stream-json/Parser.js";
 import Pick from "stream-json/filters/Pick.js";
@@ -149,6 +149,21 @@ var QueryBuilder = class {
 };
 const createQuery = () => new QueryBuilder();
 
+//#endregion
+//#region schema/request.mts
+const isAbortSignal = (value) => {
+	return value instanceof AbortSignal;
+};
+const isDispatcher = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	return typeof value.dispatch === "function";
+};
+const RequestOptions = z$1.strictObject({
+	dispatcher: z$1.custom(isDispatcher, { message: "dispatcher must expose a dispatch method" }).optional().describe("dispatcher to use for the request"),
+	signal: z$1.custom(isAbortSignal, { message: "signal must be an AbortSignal" }).optional().describe("abort signal for the request"),
+	timeout: z$1.number().nonnegative().optional().describe("request timeout in milliseconds")
+});
+
 //#endregion
 //#region schema/config.mts
 const anyArgs = z$1.array(z$1.any());
@@ -173,56 +188,61 @@ const LoggerSchema = z$1.object({
 	input: anyArgs,
 	output: z$1.void()
 }));
-const NeedleBaseOptions = z$1.object({
-	json: z$1.boolean(),
-	headers: z$1.record(z$1.string(), z$1.string()),
-	parse_response: z$1.boolean().optional()
+const CouchAuth = z$1.strictObject({
+	username: z$1.string().describe("basic auth username for CouchDB requests"),
+	password: z$1.string().describe("basic auth password for CouchDB requests")
 });
-const NeedleOptions = z$1.object({
-	json: z$1.boolean().optional(),
-	compressed: z$1.boolean().optional(),
-	follow_max: z$1.number().optional(),
-	follow_set_cookie: z$1.boolean().optional(),
-	follow_set_referer: z$1.boolean().optional(),
-	follow: z$1.number().optional(),
-	timeout: z$1.number().optional(),
-	read_timeout: z$1.number().optional(),
-	parse_response: z$1.boolean().optional(),
-	decode: z$1.boolean().optional(),
-	parse_cookies: z$1.boolean().optional(),
-	cookies: z$1.record(z$1.string(), z$1.string()).optional(),
-	headers: z$1.record(z$1.string(), z$1.string()).optional(),
-	auth: z$1.enum([
-		"auto",
-		"digest",
-		"basic"
-	]).optional(),
-	username: z$1.string().optional(),
-	password: z$1.string().optional(),
-	proxy: z$1.string().optional(),
-	agent: z$1.any().optional(),
-	rejectUnauthorized: z$1.boolean().optional(),
-	output: z$1.string().optional(),
-	parse: z$1.boolean().optional(),
-	multipart: z$1.boolean().optional(),
-	open_timeout: z$1.number().optional(),
-	response_timeout: z$1.number().optional(),
-	keepAlive: z$1.boolean().optional()
+const CouchUrl = z$1.custom((value) => {
+	try {
+		const url = new URL(value);
+		return url.username === "" && url.password === "";
+	} catch {
+		return false;
+	}
 });
 const CouchConfig = z$1.strictObject({
+	auth: CouchAuth.optional().describe("basic auth credentials for CouchDB requests"),
 	backoffFactor: z$1.number().optional().default(2).describe("multiplier for exponential backoff"),
 	bindWithRetry: z$1.boolean().optional().default(true).describe("should we bind with retry"),
-	couch: z$1.string().describe("the url of the couch db"),
+	couch: CouchUrl.describe("URL of the couch db without embedded credentials"),
 	initialDelay: z$1.number().optional().default(1e3).describe("initial retry delay in milliseconds"),
 	logger: LoggerSchema.optional().describe("logging interface supporting winston-like or simple function interface"),
 	maxRetries: z$1.number().optional().default(3).describe("maximum number of retry attempts"),
-	needleOpts: NeedleOptions.optional(),
-	throwOnGetNotFound: z$1.boolean().optional().default(false).describe("if a get is 404 should we throw or return undefined"),
+	request: RequestOptions.optional().describe("default request controls for CouchDB requests"),
+	throwOnGetNotFound: z$1.boolean().optional().default(false).describe("if true, get() throws NotFoundError on 404; otherwise it returns null"),
 	useConsoleLogger: z$1.boolean().optional().default(false).describe("turn on console as a fallback logger"),
 	"~emitter": z$1.any().optional().describe("emitter for events"),
 	"~normalizedLogger": z$1.any().optional()
 }).describe("The std config object");
 
+//#endregion
+//#region impl/utils/response.mts
+const isRecord = (value) => {
+	return value !== null && typeof value === "object";
+};
+const SUCCESS_STATUS_CODES = {
+	bulkGet: [200],
+	bulkSave: [201, 202],
+	changesFeed: [200],
+	database: [200],
+	documentDelete: [200, 202],
+	documentRead: [200],
+	documentWrite: [
+		200,
+		201,
+		202
+	],
+	viewQuery: [200],
+	viewStream: [200]
+};
+const getCouchError = (value) => {
+	if (!isRecord(value) || typeof value.error !== "string") return;
+	return value.error;
+};
+const isSuccessStatusCode = (profile, statusCode) => {
+	return SUCCESS_STATUS_CODES[profile].includes(statusCode);
+};
+
 //#endregion
 //#region impl/utils/errors.mts
 const RETRYABLE_STATUS_CODES = new Set([
@@ -248,6 +268,35 @@ const isNetworkError = (value) => {
 	const candidate = value;
 	return typeof candidate.code === "string" && candidate.code in NETWORK_ERROR_STATUS_MAP;
 };
+const getNestedNetworkError = (value) => {
+	if (isNetworkError(value)) return value;
+	if (typeof value !== "object" || value === null) return null;
+	const candidate = value;
+	return isNetworkError(candidate.cause) ? candidate.cause : null;
+};
+/**
+* Shared base class for operational errors thrown by hide-a-bed.
+*
+* @public
+*/
+var HideABedError = class extends Error {
+	category;
+	couchError;
+	docId;
+	operation;
+	retryable;
+	statusCode;
+	constructor(message, options) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "HideABedError";
+		this.category = options.category;
+		this.couchError = options.couchError;
+		this.docId = options.docId;
+		this.operation = options.operation;
+		this.retryable = options.retryable;
+		this.statusCode = options.statusCode;
+	}
+};
 /**
 * Error thrown when a requested CouchDB document cannot be found.
 *
@@ -257,21 +306,77 @@ const isNetworkError = (value) => {
 *
 * @public
 */
-var NotFoundError = class extends Error {
-	/**
-	* Identifier of the missing document.
-	*/
-	docId;
-	/**
-	* Creates a new {@link NotFoundError} instance.
-	*
-	* @param docId - The identifier of the document that was not found.
-	* @param message - Optional custom error message.
-	*/
-	constructor(docId, message = "Document not found") {
-		super(message);
+var NotFoundError = class extends HideABedError {
+	constructor(docId, options = {}) {
+		super(options.message ?? "Document not found", {
+			category: "not_found",
+			couchError: options.couchError ?? "not_found",
+			cause: options.cause,
+			docId,
+			operation: options.operation,
+			retryable: false,
+			statusCode: options.statusCode ?? 404
+		});
 		this.name = "NotFoundError";
-		this.docId = docId;
+	}
+};
+/**
+* Error thrown when a single-document mutation conflicts with the current revision.
+*
+* @public
+*/
+var ConflictError = class extends HideABedError {
+	constructor(docId, options = {}) {
+		super(options.message ?? "Document update conflict", {
+			category: "conflict",
+			couchError: options.couchError ?? "conflict",
+			cause: options.cause,
+			docId,
+			operation: options.operation,
+			retryable: false,
+			statusCode: options.statusCode ?? 409
+		});
+		this.name = "ConflictError";
+	}
+};
+/**
+* Error thrown when an operation fails in a non-retryable way.
+*
+* @public
+*/
+var OperationError = class extends HideABedError {
+	constructor(message, options = {}) {
+		super(message, {
+			category: options.category ?? "operation",
+			cause: options.cause,
+			couchError: options.couchError,
+			docId: options.docId,
+			operation: options.operation,
+			retryable: false,
+			statusCode: options.statusCode
+		});
+		this.name = "OperationError";
+	}
+};
+/**
+* Error thrown when schema validation fails for a document, row, key, or value.
+*
+* @public
+*/
+var ValidationError = class extends HideABedError {
+	issues;
+	constructor(options) {
+		super(options.message ?? "Validation failed", {
+			category: "validation",
+			cause: options.cause,
+			couchError: options.couchError,
+			docId: options.docId,
+			operation: options.operation,
+			retryable: false,
+			statusCode: options.statusCode
+		});
+		this.name = "ValidationError";
+		this.issues = options.issues;
 	}
 };
 /**
@@ -283,21 +388,18 @@ var NotFoundError = class extends Error {
 *
 * @public
 */
-var RetryableError = class RetryableError extends Error {
-	/**
-	* HTTP status code associated with the retryable failure, when available.
-	*/
-	statusCode;
-	/**
-	* Creates a new {@link RetryableError} instance.
-	*
-	* @param message - Detailed description of the failure.
-	* @param statusCode - Optional HTTP status code corresponding to the failure.
-	*/
-	constructor(message, statusCode) {
-		super(message);
+var RetryableError = class RetryableError extends HideABedError {
+	constructor(message, statusCode, options = {}) {
+		super(message, {
+			category: options.category ?? "retryable",
+			cause: options.cause,
+			couchError: options.couchError,
+			docId: options.docId,
+			operation: options.operation,
+			retryable: true,
+			statusCode
+		});
 		this.name = "RetryableError";
-		this.statusCode = statusCode;
 	}
 	/**
 	* Determines whether the provided status code should be treated as retryable.
@@ -318,15 +420,45 @@ var RetryableError = class RetryableError extends Error {
 	* @throws {@link RetryableError} When the error maps to a retryable network condition.
 	* @throws {*} Re-throws the original error when it cannot be mapped.
 	*/
-	static handleNetworkError(err) {
-		if (isNetworkError(err)) {
-			const statusCode = NETWORK_ERROR_STATUS_MAP[err.code];
-			if (statusCode) throw new RetryableError(`Network error: ${err.code}`, statusCode);
+	static handleNetworkError(err, operation = "request") {
+		const networkError = getNestedNetworkError(err);
+		if (networkError) {
+			const statusCode = NETWORK_ERROR_STATUS_MAP[networkError.code];
+			if (statusCode) throw new RetryableError("Network request failed", statusCode, {
+				category: "network",
+				cause: err,
+				operation
+			});
 		}
 		throw err;
 	}
 };
+function createResponseError({ body, defaultMessage, docId, notFoundMessage, operation, statusCode }) {
+	const couchError = getCouchError(body);
+	if (statusCode === 404 && docId) return new NotFoundError(docId, {
+		couchError,
+		message: notFoundMessage,
+		operation,
+		statusCode
+	});
+	if (statusCode === 409 && docId) return new ConflictError(docId, {
+		couchError,
+		operation,
+		statusCode
+	});
+	if (RetryableError.isRetryableStatusCode(statusCode)) return new RetryableError(defaultMessage, statusCode, {
+		couchError,
+		operation
+	});
+	return new OperationError(defaultMessage, {
+		couchError,
+		docId,
+		operation,
+		statusCode
+	});
+}
 function isConflictError(err) {
+	if (err instanceof ConflictError) return true;
 	if (typeof err !== "object" || err === null) return false;
 	return err.statusCode === 409;
 }
@@ -400,27 +532,6 @@ function createLogger(config) {
 	return normalized;
 }
 
-//#endregion
-//#region schema/util.mts
-const MergeNeedleOpts = z$1.function({
-	input: [CouchConfig, NeedleBaseOptions],
-	output: NeedleOptions
-});
-
-//#endregion
-//#region impl/utils/mergeNeedleOpts.mts
-const mergeNeedleOpts = MergeNeedleOpts.implement((config, opts) => {
-	if (config.needleOpts) return {
-		...opts,
-		...config.needleOpts,
-		headers: {
-			...opts.headers,
-			...config.needleOpts.headers ?? {}
-		}
-	};
-	return opts;
-});
-
 //#endregion
 //#region schema/couch/couch.output.schema.ts
 /**
@@ -493,8 +604,16 @@ const CouchDBInfo = z$1.looseObject({
 
 //#endregion
 //#region impl/utils/parseRows.mts
+const createValidationError = (issues, options) => {
+	return new ValidationError({
+		docId: options.docId,
+		issues,
+		message: options.defaultMessage ?? "Row validation failed",
+		operation: options.operation ?? "request"
+	});
+};
 async function parseRows(rows, options) {
-	if (!Array.isArray(rows)) throw new Error("invalid rows format");
+	if (!Array.isArray(rows)) throw new OperationError(options.defaultMessage ?? "Request failed", { operation: options.operation ?? "request" });
 	const isFinalRow = (row) => row !== "skip";
 	return (await Promise.all(rows.map(async (row) => {
 		try {
@@ -506,12 +625,20 @@ async function parseRows(rows, options) {
 				const parsedRow = z$1.looseObject(ViewRow.shape).parse(row);
 				if (options.keySchema) {
 					const parsedKey$1 = await options.keySchema["~standard"].validate(row.key);
-					if (parsedKey$1.issues) throw parsedKey$1.issues;
+					if (parsedKey$1.issues) throw createValidationError(parsedKey$1.issues, {
+						defaultMessage: options.defaultMessage,
+						docId: typeof row.id === "string" ? row.id : void 0,
+						operation: options.operation
+					});
 					parsedRow.key = parsedKey$1.value;
 				}
 				if (options.valueSchema) {
 					const parsedValue$1 = await options.valueSchema["~standard"].validate(row.value);
-					if (parsedValue$1.issues) throw parsedValue$1.issues;
+					if (parsedValue$1.issues) throw createValidationError(parsedValue$1.issues, {
+						defaultMessage: options.defaultMessage,
+						docId: typeof row.id === "string" ? row.id : void 0,
+						operation: options.operation
+					});
 					parsedRow.value = parsedValue$1.value;
 				}
 				return parsedRow;
@@ -522,17 +649,29 @@ async function parseRows(rows, options) {
 			if (options.docSchema) {
 				const parsedDocRes = await options.docSchema["~standard"].validate(row.doc);
 				if (parsedDocRes.issues) if (options.onInvalidDoc === "skip") return "skip";
-				else throw parsedDocRes.issues;
+				else throw createValidationError(parsedDocRes.issues, {
+					defaultMessage: options.defaultMessage,
+					docId: typeof row.id === "string" ? row.id : void 0,
+					operation: options.operation
+				});
 				else parsedDoc = parsedDocRes.value;
 			}
 			if (options.keySchema) {
 				const parsedKeyRes = await options.keySchema["~standard"].validate(row.key);
-				if (parsedKeyRes.issues) throw parsedKeyRes.issues;
+				if (parsedKeyRes.issues) throw createValidationError(parsedKeyRes.issues, {
+					defaultMessage: options.defaultMessage,
+					docId: typeof row.id === "string" ? row.id : void 0,
+					operation: options.operation
+				});
 				else parsedKey = parsedKeyRes.value;
 			}
 			if (options.valueSchema) {
 				const parsedValueRes = await options.valueSchema["~standard"].validate(row.value);
-				if (parsedValueRes.issues) throw parsedValueRes.issues;
+				if (parsedValueRes.issues) throw createValidationError(parsedValueRes.issues, {
+					defaultMessage: options.defaultMessage,
+					docId: typeof row.id === "string" ? row.id : void 0,
+					operation: options.operation
+				});
 				else parsedValue = parsedValueRes.value;
 			}
 			return {
@@ -548,6 +687,137 @@ async function parseRows(rows, options) {
 	}))).filter(isFinalRow);
 }
 
+//#endregion
+//#region impl/utils/request.mts
+const definedSignals = (signals) => {
+	return signals.filter((signal) => signal != null);
+};
+const composeAbortSignal = (internalSignal, request) => {
+	const timeoutSignal = typeof request?.timeout === "number" ? AbortSignal.timeout(request.timeout) : void 0;
+	const signals = definedSignals([
+		internalSignal,
+		request?.signal,
+		timeoutSignal
+	]);
+	return {
+		signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
+		timedOut: () => timeoutSignal?.aborted === true
+	};
+};
+
+//#endregion
+//#region impl/utils/fetch.mts
+const JSON_HEADERS = { "Content-Type": "application/json" };
+const hasHeader = (headers, name) => {
+	const expected = name.toLowerCase();
+	return Object.keys(headers).some((header) => header.toLowerCase() === expected);
+};
+const toBasicAuthHeader = ({ username, password }) => {
+	return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+};
+const prepareRequest = (options) => {
+	const auth = options.auth;
+	const headers = { ...options.headers ?? {} };
+	if (auth && !hasHeader(headers, "Authorization")) headers.Authorization = toBasicAuthHeader(auth);
+	return { headers };
+};
+const isAbortError = (err) => {
+	return err instanceof DOMException && err.name === "AbortError";
+};
+const isTimeoutError = (err) => {
+	return err instanceof DOMException && err.name === "TimeoutError";
+};
+const encodeBody = (body) => {
+	if (body == null) return void 0;
+	if (typeof body === "string" || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || body instanceof Blob || body instanceof FormData || body instanceof URLSearchParams || body instanceof ReadableStream) return body;
+	return JSON.stringify(body);
+};
+const parseJsonResponse = async (response) => {
+	if (response.status === 204 || response.status === 205) return null;
+	const text = await response.text();
+	if (text.trim() === "") return null;
+	try {
+		return JSON.parse(text);
+	} catch (err) {
+		if (response.ok) throw err;
+		return text;
+	}
+};
+async function fetchCouchJson(options) {
+	let response;
+	const { headers } = prepareRequest(options);
+	const { signal, timedOut } = composeAbortSignal(options.signal, options.request);
+	try {
+		response = await fetch(options.url, {
+			method: options.method,
+			headers: {
+				...JSON_HEADERS,
+				...headers
+			},
+			body: encodeBody(options.body),
+			signal,
+			dispatcher: options.request?.dispatcher
+		});
+	} catch (err) {
+		if (timedOut() || isTimeoutError(err)) throw new RetryableError("Request timed out", 503, {
+			category: "network",
+			cause: err,
+			operation: options.operation
+		});
+		if (isAbortError(err)) throw err;
+		RetryableError.handleNetworkError(err, options.operation);
+	}
+	return {
+		body: await parseJsonResponse(response),
+		headers: response.headers,
+		statusCode: response.status
+	};
+}
+async function fetchCouchStream(options) {
+	let response;
+	const { headers } = prepareRequest(options);
+	const { signal, timedOut } = composeAbortSignal(options.signal, options.request);
+	try {
+		response = await fetch(options.url, {
+			method: options.method,
+			headers,
+			body: encodeBody(options.body),
+			signal,
+			dispatcher: options.request?.dispatcher
+		});
+	} catch (err) {
+		if (timedOut() || isTimeoutError(err)) throw new RetryableError("Request timed out", 503, {
+			category: "network",
+			cause: err,
+			operation: options.operation
+		});
+		if (isAbortError(err)) throw err;
+		RetryableError.handleNetworkError(err, options.operation);
+	}
+	return {
+		body: response.body,
+		headers: response.headers,
+		statusCode: response.status
+	};
+}
+
+//#endregion
+//#region impl/utils/url.mts
+const ensureDirectoryUrl = (value) => {
+	const url = new URL(value);
+	if (!url.pathname.endsWith("/")) url.pathname = `${url.pathname}/`;
+	return url;
+};
+const createCouchDbUrl = (value) => {
+	return new URL(value);
+};
+const createCouchPathUrl = (path, base) => {
+	return new URL(path, ensureDirectoryUrl(base));
+};
+const createCouchDocUrl = (docId, base) => {
+	return new URL(encodeURIComponent(docId), ensureDirectoryUrl(base));
+};
+
 //#endregion
 //#region impl/bulkGet.mts
 /**
@@ -560,7 +830,7 @@ async function parseRows(rows, options) {
 * @returns The raw response body from CouchDB
 *
 * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
-* @throws {Error} When CouchDB returns a non-retryable error payload.
+* @throws {OperationError} When CouchDB returns a non-retryable request-level failure.
 */
 async function executeBulkGet(_config, ids, includeDocs) {
 	const configParseResult = CouchConfig.safeParse(_config);
@@ -571,26 +841,35 @@ async function executeBulkGet(_config, ids, includeDocs) {
 		throw configParseResult.error;
 	}
 	const config = configParseResult.data;
-	const url = `${config.couch}/_all_docs${includeDocs ? "?include_docs=true" : ""}`;
+	const url = createCouchPathUrl("_all_docs", config.couch);
+	if (includeDocs) url.searchParams.append("include_docs", "true");
 	const payload = { keys: ids };
-	const mergedOpts = mergeNeedleOpts(config, {
-		json: true,
-		headers: { "Content-Type": "application/json" }
-	});
 	try {
-		const resp = await needle("post", url, payload, mergedOpts);
+		const resp = await fetchCouchJson({
+			auth: config.auth,
+			method: "POST",
+			operation: "request",
+			request: config.request,
+			url,
+			body: payload
+		});
 		if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
 			logger.warn(`Retryable status code received: ${resp.statusCode}`);
-			throw new RetryableError("retryable error during bulk get", resp.statusCode);
+			throw new RetryableError("Bulk get failed", resp.statusCode, { operation: "request" });
 		}
-		if (resp.statusCode !== 200) {
+		if (!isSuccessStatusCode("bulkGet", resp.statusCode)) {
 			logger.error(`Unexpected status code: ${resp.statusCode}`);
-			throw new Error("could not fetch");
+			throw createResponseError({
+				body: resp.body,
+				defaultMessage: "Bulk get failed",
+				operation: "request",
+				statusCode: resp.statusCode
+			});
 		}
 		return resp.body;
 	} catch (err) {
 		logger.error("Network error during bulk get:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, "request");
 	}
 }
 /**
@@ -605,16 +884,22 @@ async function executeBulkGet(_config, ids, includeDocs) {
 * @returns The bulk get response with rows optionally validated against the supplied document schema.
 *
 * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
-* @throws {Error<StandardSchemaV1.FailureResult["issues"]>} When the configuration or validation schemas fail to parse.
-* @throws {Error} When CouchDB returns a non-retryable error payload.
+* @throws {ValidationError} When returned documents fail schema validation.
+* @throws {OperationError} When CouchDB returns a non-retryable request-level failure.
 */
 async function _bulkGetWithOptions(config, ids, options = {}) {
 	const body = await executeBulkGet(config, ids, options.includeDocs ?? true);
-	if (!body) throw new RetryableError("no response", 503);
-	if (body.error) throw new Error(typeof body.reason === "string" ? body.reason : "could not fetch");
+	if (!body) throw new RetryableError("Bulk get failed", 503, { operation: "request" });
+	if (body.error) throw createResponseError({
+		body,
+		defaultMessage: "Bulk get failed",
+		operation: "request"
+	});
 	const docSchema = options.validate?.docSchema || CouchDoc;
 	const rows = await parseRows(body.rows, {
+		defaultMessage: "Bulk get failed",
 		onInvalidDoc: options.validate?.onInvalidDoc,
+		operation: "request",
 		docSchema
 	});
 	return {
@@ -640,8 +925,8 @@ async function _bulkGetWithOptions(config, ids, options = {}) {
 * @returns The bulk get response with rows optionally validated against the supplied document schema.
 *
 * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
-* @throws {Error<StandardSchemaV1.FailureResult["issues"]>} When the configuration or validation schemas fail to parse.
-* @throws {Error} When CouchDB returns a non-retryable error payload.
+* @throws {ValidationError} When returned documents fail schema validation.
+* @throws {OperationError} When CouchDB returns a non-retryable request-level failure.
 */
 async function bulkGet(config, ids, options = {}) {
 	return _bulkGetWithOptions(config, ids, {
@@ -652,7 +937,7 @@ async function bulkGet(config, ids, options = {}) {
 /**
 * Bulk get documents by IDs and return a dictionary of found and not found documents.
 *
-* @template DocSchema - Schema used to validate each returned document, if provided. Note: if a document is found and it fails validation this will throw a Error<StandardSchemaV1.FailureResult["issues"]>.
+* @template DocSchema - Schema used to validate each returned document, if provided. Note: if a document is found and it fails validation this will throw a ValidationError.
 *
 * @param config - CouchDB configuration data that is validated before use.
 * @param ids - Array of document IDs to retrieve.
@@ -661,8 +946,8 @@ async function bulkGet(config, ids, options = {}) {
 * @returns An object containing found documents and not found rows.
 *
 * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
-* @throws {Error<StandardSchemaV1.FailureResult["issues"]>} When the configuration or validation schemas fail to parse.
-* @throws {Error} When CouchDB returns a non-retryable error payload.
+* @throws {ValidationError} When returned documents fail schema validation.
+* @throws {OperationError} When CouchDB returns a non-retryable request-level failure.
 */
 async function bulkGetDictionary(config, ids, options) {
 	const response = await bulkGet(config, ids, {
@@ -693,60 +978,65 @@ async function bulkGetDictionary(config, ids, options) {
 
 //#endregion
 //#region impl/get.mts
-const ValidSchema = z$1.custom((value) => {
+const ValidSchema$1 = z$1.custom((value) => {
 	return value !== null && typeof value === "object" && "~standard" in value;
 }, { message: "docSchema must be a valid StandardSchemaV1 schema" });
-const CouchGetOptions = z$1.object({
+const CouchGetOptions = z$1.strictObject({
 	rev: z$1.string().optional().describe("the couch doc revision"),
-	validate: z$1.object({ docSchema: ValidSchema.optional() }).optional().describe("optional document validation rules")
+	validate: z$1.object({ docSchema: ValidSchema$1.optional() }).optional().describe("optional document validation rules")
 });
-async function _getWithOptions(config, id, options) {
-	const parsedOptions = CouchGetOptions.parse({
-		rev: options.rev,
-		validate: options.validate
-	});
+async function _getWithOptions(configInput, id, options) {
+	const config = CouchConfig.parse(configInput);
+	const parsedOptions = CouchGetOptions.parse(options);
 	const logger = createLogger(config);
 	const rev = parsedOptions.rev;
-	const path = rev ? `${id}?rev=${rev}` : id;
-	const url = `${config.couch}/${path}`;
-	const requestOptions = mergeNeedleOpts(config, {
-		json: true,
-		headers: { "Content-Type": "application/json" }
-	});
+	const operation = rev ? "getAtRev" : "get";
+	const url = createCouchDocUrl(id, config.couch);
+	if (rev) url.searchParams.set("rev", rev);
 	logger.info(`Getting document with id: ${id}, rev ${rev ?? "latest"}`);
 	try {
-		const resp = await needle("get", url, null, requestOptions);
+		const resp = await fetchCouchJson({
+			auth: config.auth,
+			method: "GET",
+			operation,
+			request: config.request,
+			url
+		});
 		if (!resp) {
 			logger.error("No response received from get request");
-			throw new RetryableError("no response", 503);
+			throw new RetryableError("Request failed", 503, { operation });
 		}
 		const body = resp.body ?? null;
 		if (resp.statusCode === 404) {
-			if (config.throwOnGetNotFound) {
-				const reason = typeof body?.reason === "string" ? body.reason : "not_found";
-				logger.warn(`Document not found (throwing error): ${id}, rev ${rev ?? "latest"}`);
-				throw new NotFoundError(id, reason);
-			}
-			logger.debug(`Document not found (returning undefined): ${id}, rev ${rev ?? "latest"}`);
-			return null;
+			logger.warn(`Document not found: ${id}, rev ${rev ?? "latest"}`);
+			if (config.throwOnGetNotFound === false) return null;
+			throw new NotFoundError(id, {
+				operation,
+				statusCode: resp.statusCode
+			});
 		}
-		if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
-			const reason = typeof body?.reason === "string" ? body.reason : "retryable error";
-			logger.warn(`Retryable status code received: ${resp.statusCode}`);
-			throw new RetryableError(reason, resp.statusCode);
-		}
-		if (resp.statusCode !== 200) {
-			const reason = typeof body?.reason === "string" ? body.reason : "failed";
+		if (!isSuccessStatusCode("documentRead", resp.statusCode)) {
 			logger.error(`Unexpected status code: ${resp.statusCode}`);
-			throw new Error(reason);
+			throw createResponseError({
+				body,
+				defaultMessage: "Failed to fetch document",
+				docId: id,
+				operation,
+				statusCode: resp.statusCode
+			});
 		}
 		const typedDoc = await (parsedOptions.validate?.docSchema ?? CouchDoc)["~standard"].validate(body);
-		if (typedDoc.issues) throw typedDoc.issues;
+		if (typedDoc.issues) throw new ValidationError({
+			docId: id,
+			issues: typedDoc.issues,
+			message: "Document validation failed",
+			operation
+		});
 		logger.info(`Successfully retrieved document: ${id}, rev ${rev ?? "latest"}`);
 		return typedDoc.value;
 	} catch (err) {
 		logger.error("Error during get operation:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, operation);
 	}
 }
 async function get(config, id, options) {
@@ -834,89 +1124,137 @@ function queryString(options = {}) {
 */
 async function queryStream(rawConfig, view, options, onRow) {
 	return new Promise((resolve, reject) => {
-		const config = CouchConfig.parse(rawConfig);
-		const logger = createLogger(config);
-		logger.info(`Starting view query stream: ${view}`);
-		logger.debug("Query options:", options);
-		const queryOptions = options ?? {};
-		let method = "GET";
-		let payload = null;
-		let qs = queryString(queryOptions);
-		logger.debug("Generated query string:", qs);
-		if (typeof queryOptions.keys !== "undefined") {
-			const MAX_URL_LENGTH = 2e3;
-			const keysAsString = `keys=${encodeURIComponent(JSON.stringify(queryOptions.keys))}`;
-			if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) qs += (qs.length > 0 ? "&" : "") + keysAsString;
-			else {
-				method = "POST";
-				payload = { keys: queryOptions.keys };
-			}
-		}
-		const url = `${config.couch}/${view}?${qs}`;
-		const mergedOpts = mergeNeedleOpts(config, {
-			json: true,
-			headers: { "Content-Type": "application/json" },
-			parse_response: false
-		});
-		const parserPipeline = Chain.chain([
-			new Parser(),
-			new Pick({ filter: "rows" }),
-			new StreamArray()
-		]);
-		let rowCount = 0;
-		let settled = false;
-		const settleReject = (err) => {
-			if (settled) return;
-			settled = true;
-			reject(err);
-		};
-		const settleResolve = () => {
-			if (settled) return;
-			settled = true;
-			resolve();
-		};
-		let request = null;
-		parserPipeline.on("data", (chunk) => {
-			try {
-				rowCount++;
-				onRow(chunk.value);
-			} catch (callbackErr) {
-				const error = callbackErr instanceof Error ? callbackErr : new Error(String(callbackErr));
-				parserPipeline.destroy(error);
-				settleReject(error);
-			}
-		});
-		parserPipeline.on("error", (err) => {
-			logger.error("Stream parsing error:", err);
-			parserPipeline.destroy();
-			settleReject(new Error(`Stream parsing error: ${err.message}`, { cause: err }));
-		});
-		parserPipeline.on("end", () => {
-			logger.info(`Stream completed, processed ${rowCount} rows`);
-			settleResolve();
-		});
-		request = method === "GET" ? needle.get(url, mergedOpts) : needle.post(url, payload, mergedOpts);
-		request.on("response", (response) => {
-			logger.debug(`Received response with status code: ${response.statusCode}`);
-			if (RetryableError.isRetryableStatusCode(response.statusCode)) {
-				logger.warn(`Retryable status code received: ${response.statusCode}`);
-				settleReject(new RetryableError("retryable error during stream query", response.statusCode));
-				request.destroy();
+		(async () => {
+			const config = CouchConfig.parse(rawConfig);
+			const logger = createLogger(config);
+			logger.info(`Starting view query stream: ${view}`);
+			const queryOptions = ViewOptions.parse(options ?? {});
+			const request = config.request;
+			logger.debug("Query options:", {
+				...queryOptions,
+				request
+			});
+			let method = "GET";
+			let payload = null;
+			let qs = queryString(queryOptions);
+			logger.debug("Generated query string:", qs);
+			if (typeof queryOptions.keys !== "undefined") {
+				const MAX_URL_LENGTH = 2e3;
+				const keysAsString = `keys=${encodeURIComponent(JSON.stringify(queryOptions.keys))}`;
+				if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) qs += (qs.length > 0 ? "&" : "") + keysAsString;
+				else {
+					method = "POST";
+					payload = { keys: queryOptions.keys };
+				}
 			}
-		});
-		request.on("error", (err) => {
-			logger.error("Network error during stream query:", err);
-			parserPipeline.destroy(err);
+			const url = createCouchPathUrl(view, config.couch);
+			if (qs) url.search = qs;
+			const requestHeaders = { "Content-Type": "application/json" };
+			const abortController = new AbortController();
+			const requestAbortHandler = () => {
+				const reason = request?.signal?.reason instanceof Error ? request.signal.reason : new DOMException("The operation was aborted.", "AbortError");
+				abortController.abort(reason);
+				responseStream?.destroy(reason);
+				parserPipeline.destroy(reason);
+				settleReject(reason);
+			};
+			const parserPipeline = Chain.chain([
+				new Parser(),
+				new Pick({ filter: "rows" }),
+				new StreamArray()
+			]);
+			let rowCount = 0;
+			let settled = false;
+			const settleReject = (err) => {
+				if (settled) return;
+				settled = true;
+				request?.signal?.removeEventListener("abort", requestAbortHandler);
+				reject(err);
+			};
+			const settleResolve = () => {
+				if (settled) return;
+				settled = true;
+				request?.signal?.removeEventListener("abort", requestAbortHandler);
+				resolve();
+			};
+			let responseStream = null;
+			request?.signal?.addEventListener("abort", requestAbortHandler, { once: true });
+			parserPipeline.on("data", (chunk) => {
+				try {
+					rowCount++;
+					onRow(chunk.value);
+				} catch (callbackErr) {
+					const error = callbackErr instanceof Error ? callbackErr : new Error(String(callbackErr));
+					parserPipeline.destroy(error);
+					settleReject(error);
+				}
+			});
+			parserPipeline.on("error", (err) => {
+				logger.error("Stream parsing error:", err);
+				parserPipeline.destroy();
+				settleReject(new OperationError("Stream parsing failed", {
+					cause: err,
+					operation: "queryStream"
+				}));
+			});
+			parserPipeline.on("end", () => {
+				logger.info(`Stream completed, processed ${rowCount} rows`);
+				settleResolve();
+			});
 			try {
-				RetryableError.handleNetworkError(err);
-			} catch (retryErr) {
-				settleReject(retryErr);
-				return;
-			} finally {
-				settleReject(err);
+				const response = await fetchCouchStream({
+					auth: config.auth,
+					method,
+					operation: "queryStream",
+					url,
+					body: method === "POST" ? payload : void 0,
+					headers: requestHeaders,
+					request,
+					signal: abortController.signal
+				});
+				logger.debug(`Received response with status code: ${response.statusCode}`);
+				if (RetryableError.isRetryableStatusCode(response.statusCode)) {
+					logger.warn(`Retryable status code received: ${response.statusCode}`);
+					abortController.abort();
+					settleReject(new RetryableError("Stream query failed", response.statusCode, { operation: "queryStream" }));
+					return;
+				}
+				if (!isSuccessStatusCode("viewStream", response.statusCode)) {
+					abortController.abort();
+					settleReject(createResponseError({
+						defaultMessage: "Stream query failed",
+						operation: "queryStream",
+						statusCode: response.statusCode
+					}));
+					return;
+				}
+				if (!response.body) {
+					settleReject(new RetryableError("Stream query failed", 503, { operation: "queryStream" }));
+					return;
+				}
+				responseStream = Readable.fromWeb(response.body);
+				responseStream.on("error", (err) => {
+					logger.error("Network error during stream query:", err);
+					parserPipeline.destroy(err);
+					try {
+						RetryableError.handleNetworkError(err, "queryStream");
+					} catch (retryErr) {
+						settleReject(retryErr);
+						return;
+					}
+				});
+				responseStream.pipe(parserPipeline);
+			} catch (err) {
+				logger.error("Network error during stream query:", err);
+				parserPipeline.destroy(err);
+				try {
+					RetryableError.handleNetworkError(err, "queryStream");
+				} catch (retryErr) {
+					settleReject(retryErr);
+					return;
+				}
 			}
-		});
-		request.pipe(parserPipeline);
+		})();
 	});
 }
 
@@ -925,35 +1263,46 @@ async function queryStream(rawConfig, view, options, onRow) {
 const put = async (configInput, doc) => {
 	const config = CouchConfig.parse(configInput);
 	const logger = createLogger(config);
-	const url = `${config.couch}/${doc._id}`;
+	const url = createCouchDocUrl(doc._id, config.couch);
 	const body = doc;
-	const mergedOpts = mergeNeedleOpts(config, {
-		json: true,
-		headers: { "Content-Type": "application/json" }
-	});
 	logger.info(`Putting document with id: ${doc._id}`);
 	let resp;
 	try {
-		resp = await needle("put", url, body, mergedOpts);
+		resp = await fetchCouchJson({
+			auth: config.auth,
+			method: "PUT",
+			operation: "put",
+			request: config.request,
+			url,
+			body
+		});
 	} catch (err) {
 		logger.error("Error during put operation:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, "put");
 	}
 	if (!resp) {
 		logger.error("No response received from put request");
-		throw new RetryableError("no response", 503);
+		throw new RetryableError("Put failed", 503, { operation: "put" });
 	}
-	const result = resp?.body || {};
+	const result = { ...isRecord(resp.body) ? resp.body : {} };
 	result.statusCode = resp.statusCode;
 	if (resp.statusCode === 409) {
 		logger.warn(`Conflict detected for document: ${doc._id}`);
-		result.ok = false;
-		result.error = "conflict";
-		return CouchPutResponse.parse(result);
+		throw new ConflictError(doc._id, {
+			couchError: typeof result.error === "string" ? result.error : void 0,
+			operation: "put",
+			statusCode: resp.statusCode
+		});
 	}
-	if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
-		logger.warn(`Retryable status code received: ${resp.statusCode}`);
-		throw new RetryableError(result.reason || "retryable error", resp.statusCode);
+	if (!isSuccessStatusCode("documentWrite", resp.statusCode) || !result.ok) {
+		logger.error(`Unexpected status code: ${resp.statusCode}`);
+		throw createResponseError({
+			body: resp.body,
+			defaultMessage: "Put failed",
+			docId: doc._id,
+			operation: "put",
+			statusCode: resp.statusCode
+		});
 	}
 	logger.info(`Successfully saved document: ${doc._id}`);
 	return CouchPutResponse.parse(result);
@@ -971,7 +1320,10 @@ const PatchProperties = z$1.looseObject({ _rev: z$1.string("_rev is required for
 * @param _properties - Properties to merge into the document (must include _rev)
 * @returns The result of the put operation
 *
-* @throws Error if the _rev does not match or other errors occur
+* @throws {ConflictError} When the supplied `_rev` does not match the current document revision.
+* @throws {NotFoundError} When the document does not exist.
+* @throws {RetryableError} When a retryable transport or HTTP failure occurs while reading or saving.
+* @throws {OperationError} When a non-retryable operational failure occurs.
 */
 const patch = async (configInput, id, _properties) => {
 	const config = CouchConfig.parse(configInput);
@@ -979,12 +1331,15 @@ const patch = async (configInput, id, _properties) => {
 	const logger = createLogger(configInput);
 	logger.info(`Starting patch operation for document ${id}`);
 	logger.debug("Patch properties:", properties);
-	const doc = await get(config, id);
-	if (doc?._rev !== properties._rev) return {
-		statusCode: 409,
-		ok: false,
-		error: "conflict"
-	};
+	const doc = await get({
+		...config,
+		throwOnGetNotFound: true
+	}, id);
+	if (!doc) throw new OperationError("Patch failed", {
+		docId: id,
+		operation: "patch"
+	});
+	if (doc._rev !== properties._rev) throw new ConflictError(id, { operation: "patch" });
 	const updatedDoc = {
 		...doc,
 		...properties
@@ -1005,7 +1360,9 @@ const patch = async (configInput, id, _properties) => {
 * @param properties - Properties to merge into the document
 * @returns The result of the put operation or an error if max retries are exceeded
 *
-* @throws Error if max retries are exceeded or other errors occur
+* @throws {NotFoundError} When the document does not exist.
+* @throws {RetryableError} When a retryable transport or HTTP failure occurs before retries are exhausted.
+* @throws {OperationError} When retries are exhausted or a non-retryable operational failure occurs.
 */
 const patchDangerously = async (configInput, id, properties) => {
 	const config = CouchConfig.parse(configInput);
@@ -1015,65 +1372,66 @@ const patchDangerously = async (configInput, id, properties) => {
 	let attempts = 0;
 	logger.info(`Starting patch operation for document ${id}`);
 	logger.debug("Patch properties:", properties);
+	let lastError;
 	while (attempts <= maxRetries) {
 		logger.debug(`Attempt ${attempts + 1} of ${maxRetries + 1}`);
 		try {
-			const doc = await get(config, id);
-			if (!doc) {
-				logger.warn(`Document ${id} not found`);
-				return {
-					ok: false,
-					statusCode: 404,
-					error: "not_found"
-				};
-			}
+			const doc = await get({
+				...config,
+				throwOnGetNotFound: true
+			}, id);
+			if (!doc) throw new OperationError("Patch failed", {
+				docId: id,
+				operation: "patchDangerously"
+			});
 			const updatedDoc = {
 				...doc,
 				...properties
 			};
 			logger.debug("Merged document:", updatedDoc);
 			const result = await put(config, updatedDoc);
-			if (result.ok) {
-				logger.info(`Successfully patched document ${id}, rev: ${result.rev}`);
-				return result;
-			}
-			attempts++;
-			if (attempts > maxRetries) {
-				logger.error(`Failed to patch ${id} after ${maxRetries} attempts`);
-				throw new Error(`Failed to patch after ${maxRetries} attempts`);
-			}
-			logger.warn(`Conflict detected for ${id}, retrying (attempt ${attempts})`);
-			await setTimeout$1(delay);
-			delay *= config.backoffFactor || 2;
-			logger.debug(`Next retry delay: ${delay}ms`);
+			logger.info(`Successfully patched document ${id}, rev: ${result.rev}`);
+			return result;
 		} catch (err) {
-			if (typeof err === "object" && err !== null && "message" in err && err.message === "not_found") {
-				logger.warn(`Document ${id} not found during patch operation`);
-				return {
-					ok: false,
-					statusCode: 404,
-					error: "not_found"
-				};
-			}
+			if (!(err instanceof Error)) throw err;
+			if (!(err instanceof ConflictError) && !(err instanceof RetryableError)) throw err;
+			lastError = err;
 			attempts++;
 			if (attempts > maxRetries) {
-				const error = `Failed to patch after ${maxRetries} attempts: ${err}`;
-				logger.error(error);
-				return {
-					ok: false,
-					statusCode: 500,
-					error
-				};
+				logger.error(`Failed to patch ${id} after ${maxRetries} attempts`, err);
+				throw new OperationError("Patch failed", {
+					cause: err,
+					couchError: err instanceof HideABedError ? err.couchError : void 0,
+					docId: id,
+					operation: "patchDangerously",
+					statusCode: err instanceof HideABedError ? err.statusCode : void 0
+				});
 			}
 			logger.warn(`Error during patch attempt ${attempts}: ${err}`);
 			await setTimeout$1(delay);
+			delay *= config.backoffFactor || 2;
 			logger.debug(`Retrying after ${delay}ms`);
 		}
 	}
+	throw new OperationError("Patch failed", {
+		cause: lastError,
+		docId: id,
+		operation: "patchDangerously"
+	});
 };
 
 //#endregion
 //#region impl/query.mts
+const ValidSchema = z$1.custom((value) => {
+	return value !== null && typeof value === "object" && "~standard" in value;
+}, { message: "schema must be a valid StandardSchemaV1 schema" });
+const QueryValidationSchema = z$1.object({
+	docSchema: ValidSchema.optional(),
+	keySchema: ValidSchema.optional(),
+	onInvalidDoc: z$1.enum(["skip", "throw"]).optional(),
+	valueSchema: ValidSchema.optional()
+}).optional();
+const QueryOptionsSchema = ViewOptions.extend({ validate: QueryValidationSchema }).strict();
 /**
 * Executes a CouchDB view query with optional schema validation and automatic handling
 * of HTTP method selection, query string construction, and retryable errors.
@@ -1093,69 +1451,85 @@ const patchDangerously = async (configInput, id, properties) => {
 * @returns The parsed view response with rows validated against the supplied schemas.
 *
 * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
-* @throws {Error<Array<StandardSchemaV1.Issue>>} When the configuration or validation schemas fail to parse.
-* @throws {Error} When CouchDB returns a non-retryable error payload.
+* @throws {ValidationError} When row, key, value, or included document validation fails.
+* @throws {OperationError} When CouchDB returns a non-retryable response or malformed row payload.
 */
 async function query(_config, view, options = {}) {
 	const configParseResult = CouchConfig.safeParse(_config);
+	const parsedOptions = QueryOptionsSchema.parse(options || {});
 	const logger = createLogger(_config);
 	logger.info(`Starting view query: ${view}`);
-	logger.debug("Query options:", ViewOptions.parse(options || {}));
+	logger.debug("Query options:", parsedOptions);
 	if (!configParseResult.success) {
 		logger.error(`Invalid configuration provided: ${z$1.prettifyError(configParseResult.error)}`);
 		throw configParseResult.error;
 	}
 	const config = configParseResult.data;
-	let qs = queryString(options);
-	let method = "get";
+	let qs = queryString(parsedOptions);
+	let method = "GET";
 	let payload = null;
-	const mergedOpts = mergeNeedleOpts(config, {
-		json: true,
-		headers: { "Content-Type": "application/json" }
-	});
-	if (typeof options.keys !== "undefined") {
+	if (typeof parsedOptions.keys !== "undefined") {
 		const MAX_URL_LENGTH = 2e3;
-		const _options = structuredClone(options);
-		delete _options.keys;
-		qs = queryString(_options);
-		const keysAsString = `keys=${JSON.stringify(options.keys)}`;
+		const { keys, validate, ...queryableOptions } = parsedOptions;
+		qs = queryString(queryableOptions);
+		const keysAsString = `keys=${JSON.stringify(keys)}`;
 		if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) {
-			method = "get";
+			method = "GET";
 			if (qs.length > 0) qs += "&";
 			else qs = "";
 			qs += keysAsString;
 		} else {
-			method = "post";
-			payload = { keys: options.keys };
+			method = "POST";
+			payload = { keys: parsedOptions.keys };
 		}
 	}
 	logger.debug("Generated query string:", qs);
-	const url = `${config.couch}/${view}?${qs}`;
+	const url = createCouchPathUrl(view, config.couch);
+	if (qs) url.search = qs;
 	let results;
 	try {
 		logger.debug(`Sending ${method} request to: ${url}`);
-		results = method === "get" ? await needle("get", url, mergedOpts) : await needle("post", url, payload, mergedOpts);
+		results = await fetchCouchJson({
+			auth: config.auth,
+			method,
+			operation: "query",
+			request: config.request,
+			url,
+			body: method === "POST" ? payload : void 0
+		});
 	} catch (err) {
 		logger.error("Network error during query:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, "query");
 	}
 	if (!results) {
 		logger.error("No response received from query request");
-		throw new RetryableError("no response", 503);
+		throw new RetryableError("Query failed", 503, { operation: "query" });
 	}
 	const body = results.body;
-	if (RetryableError.isRetryableStatusCode(results.statusCode)) {
-		logger.warn(`Retryable status code received: ${results.statusCode}`);
-		throw new RetryableError(body.error || "retryable error during query", results.statusCode);
-	}
-	if (body.error) {
-		logger.error(`Query error: ${JSON.stringify(body)}`);
-		throw new Error(`CouchDB query error: ${body.error} - ${body.reason || ""}`);
+	if (!isSuccessStatusCode("viewQuery", results.statusCode) || body.error) {
+		if (body.error) logger.error(`Query error: ${JSON.stringify(body)}`);
+		else logger.error(`Unexpected status code: ${results.statusCode}`);
+		throw createResponseError({
+			body,
+			defaultMessage: "Query failed",
+			operation: "query",
+			statusCode: results.statusCode
+		});
 	}
-	if (options.validate && body.rows) body.rows = await parseRows(body.rows, options.validate);
+	const rows = options.validate && body.rows ? await parseRows(body.rows, {
+		...options.validate,
+		defaultMessage: "Query failed",
+		operation: "query"
+	}) : body.rows ?? [];
 	logger.info(`Successfully executed view query: ${view}`);
-	logger.debug("Query response:", body);
-	return body;
+	logger.debug("Query response:", {
+		...body,
+		rows
+	});
+	return {
+		...body,
+		rows
+	};
 }
 
 //#endregion
@@ -1167,35 +1541,35 @@ const setupEmitter = (config) => {
 
 //#endregion
 //#region impl/utils/transactionErrors.mts
-var TransactionSetupError = class extends Error {
+var TransactionSetupError = class extends OperationError {
 	details;
 	constructor(message, details = {}) {
-		super(message);
+		super(message, { category: "transaction" });
 		this.name = "TransactionSetupError";
 		this.details = details;
 	}
 };
-var TransactionVersionConflictError = class extends Error {
+var TransactionVersionConflictError = class extends OperationError {
 	conflictingIds;
 	constructor(conflictingIds) {
-		super(`Revision mismatch for documents: ${conflictingIds.join(", ")}`);
+		super(`Revision mismatch for documents: ${conflictingIds.join(", ")}`, { category: "transaction" });
 		this.name = "TransactionVersionConflictError";
 		this.conflictingIds = conflictingIds;
 	}
 };
-var TransactionBulkOperationError = class extends Error {
+var TransactionBulkOperationError = class extends OperationError {
 	failedDocs;
 	constructor(failedDocs) {
-		super(`Failed to save documents: ${failedDocs.map((d) => d.id).join(", ")}`);
+		super(`Failed to save documents: ${failedDocs.map((d) => d.id).join(", ")}`, { category: "transaction" });
 		this.name = "TransactionBulkOperationError";
 		this.failedDocs = failedDocs;
 	}
 };
-var TransactionRollbackError = class extends Error {
+var TransactionRollbackError = class extends OperationError {
 	originalError;
 	rollbackResults;
 	constructor(message, originalError, rollbackResults) {
-		super(message);
+		super(message, { category: "transaction" });
 		this.name = "TransactionRollbackError";
 		this.originalError = originalError;
 		this.rollbackResults = rollbackResults;
@@ -1215,39 +1589,48 @@ var TransactionRollbackError = class extends Error {
 * @returns {Promise<BulkSaveResponse>} - The response from CouchDB after the bulk save operation.
 *
 * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
-* @throws {Error} When CouchDB returns a non-retryable error payload.
+* @throws {OperationError} When bulk save input is invalid or CouchDB returns a non-retryable request-level failure.
 */
 const bulkSave = async (config, docs) => {
-	const logger = createLogger(config);
+	const parsedConfig = CouchConfig.parse(config);
+	const logger = createLogger(parsedConfig);
 	if (docs == null || !docs.length) {
 		logger.error("bulkSave called with no docs");
-		throw new Error("no docs provided");
+		throw new OperationError("Bulk save requires at least one document", { operation: "request" });
 	}
 	logger.info(`Starting bulk save of ${docs.length} documents`);
-	const url = `${config.couch}/_bulk_docs`;
+	const url = createCouchPathUrl("_bulk_docs", parsedConfig.couch);
 	const body = { docs };
-	const mergedOpts = mergeNeedleOpts(config, {
-		json: true,
-		headers: { "Content-Type": "application/json" }
-	});
 	let resp;
 	try {
-		resp = await needle("post", url, body, mergedOpts);
+		resp = await fetchCouchJson({
+			auth: parsedConfig.auth,
+			method: "POST",
+			operation: "request",
+			request: parsedConfig.request,
+			url,
+			body
+		});
 	} catch (err) {
 		logger.error("Network error during bulk save:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, "request");
 	}
 	if (!resp) {
 		logger.error("No response received from bulk save request");
-		throw new RetryableError("no response", 503);
+		throw new RetryableError("Bulk save failed", 503, { operation: "request" });
 	}
 	if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
 		logger.warn(`Retryable status code received: ${resp.statusCode}`);
-		throw new RetryableError("retryable error during bulk save", resp.statusCode);
+		throw new RetryableError("Bulk save failed", resp.statusCode, { operation: "request" });
 	}
-	if (resp.statusCode !== 201) {
+	if (!isSuccessStatusCode("bulkSave", resp.statusCode)) {
 		logger.error(`Unexpected status code: ${resp.statusCode}`);
-		throw new Error("could not save");
+		throw createResponseError({
+			body: resp.body,
+			defaultMessage: "Bulk save failed",
+			operation: "request",
+			statusCode: resp.statusCode
+		});
 	}
 	const results = resp?.body || [];
 	return BulkSaveResponse.parse(results);
@@ -1310,16 +1693,21 @@ const bulkSaveTransaction = async (config, transactionId, docs) => {
 		changes: docs,
 		timestamp: (/* @__PURE__ */ new Date()).toISOString()
 	};
-	let transactionResponse = await _put(transactionDoc);
+	let transactionResponse;
+	try {
+		transactionResponse = await _put(transactionDoc);
+	} catch (error) {
+		if (error instanceof ConflictError) throw new TransactionSetupError("Failed to create transaction document", {
+			error: error.couchError,
+			response: error
+		});
+		throw error;
+	}
 	logger.debug("Transaction document created:", transactionDoc, transactionResponse);
 	await emitter.emit("transaction-created", {
 		transactionResponse,
 		txnDoc: transactionDoc
 	});
-	if (transactionResponse.error) throw new TransactionSetupError("Failed to create transaction document", {
-		error: transactionResponse.error,
-		response: transactionResponse
-	});
 	const existingDocs = await bulkGetDictionary(config, docs.map((d) => d._id));
 	logger.debug("Fetched current revisions of documents:", existingDocs);
 	await emitter.emit("transaction-revs-fetched", existingDocs);
@@ -1412,44 +1800,44 @@ const bulkSaveTransaction = async (config, transactionId, docs) => {
 const remove = async (configInput, id, rev) => {
 	const config = CouchConfig.parse(configInput);
 	const logger = createLogger(config);
-	const url = `${config.couch}/${id}?rev=${rev}`;
-	const mergedOpts = mergeNeedleOpts(config, {
-		json: true,
-		headers: { "Content-Type": "application/json" }
-	});
+	const url = createCouchDocUrl(id, config.couch);
+	url.searchParams.set("rev", rev);
 	logger.info(`Deleting document with id: ${id}`);
 	let resp;
 	try {
-		resp = await needle("delete", url, null, mergedOpts);
+		resp = await fetchCouchJson({
+			auth: config.auth,
+			method: "DELETE",
+			operation: "remove",
+			request: config.request,
+			url
+		});
 	} catch (err) {
 		logger.error("Error during delete operation:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, "remove");
 	}
 	if (!resp) {
 		logger.error("No response received from delete request");
-		throw new RetryableError("no response", 503);
-	}
-	let result;
-	if (typeof resp.body === "string") try {
-		result = JSON.parse(resp.body);
-	} catch {
-		result = {};
+		throw new RetryableError("Remove failed", 503, { operation: "remove" });
 	}
-	else result = resp.body || {};
+	const result = { ...isRecord(resp.body) ? resp.body : {} };
 	result.statusCode = resp.statusCode;
 	if (resp.statusCode === 404) {
 		logger.warn(`Document not found for deletion: ${id}`);
-		result.ok = false;
-		result.error = "not_found";
-		return CouchPutResponse.parse(result);
-	}
-	if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
-		logger.warn(`Retryable status code received: ${resp.statusCode}`);
-		throw new RetryableError(result.reason || "retryable error", resp.statusCode);
+		throw new NotFoundError(id, {
+			operation: "remove",
+			statusCode: resp.statusCode
+		});
 	}
-	if (resp.statusCode !== 200) {
+	if (!isSuccessStatusCode("documentDelete", resp.statusCode) || !result.ok) {
 		logger.error(`Unexpected status code: ${resp.statusCode}`);
-		throw new Error(result.reason || "failed");
+		throw createResponseError({
+			body: resp.body,
+			defaultMessage: "Remove failed",
+			docId: id,
+			operation: "remove",
+			statusCode: resp.statusCode
+		});
 	}
 	logger.info(`Successfully deleted document: ${id}`);
 	return CouchPutResponse.parse(result);
@@ -1479,7 +1867,8 @@ const remove = async (configInput, id, rev) => {
 * console.log(results);
 * ```
 *
-* @throws Will throw an error if the provided configuration is invalid or if the bulk delete operation fails.
+* @throws {RetryableError} When the bulk request fails with a retryable transport or HTTP error.
+* @throws {OperationError} When CouchDB returns a non-retryable request-level failure.
 */
 const bulkRemove = async (configInput, ids) => {
 	const config = CouchConfig.parse(configInput);
@@ -1521,7 +1910,8 @@ const bulkRemove = async (configInput, ids) => {
 * console.log(results);
 * ```
 *
-* @throws Will throw an error if the provided configuration is invalid or if any delete operation fails.
+* @throws {RetryableError} When a request-level transport or retryable HTTP failure occurs.
+* @throws {OperationError} When a request fails in a non-retryable way.
 */
 const bulkRemoveMap = async (configInput, ids) => {
 	const config = CouchConfig.parse(configInput);
@@ -1550,7 +1940,7 @@ const bulkRemoveMap = async (configInput, ids) => {
 * @param configInput - The CouchDB configuration input.
 * @returns A promise that resolves to the CouchDB database information.
 * @throws {RetryableError} `RetryableError` If a retryable error occurs during the request.
-* @throws {Error} `Error` For other non-retryable errors.
+* @throws {OperationError} `OperationError` For other non-retryable response failures.
 *
 * @example
 * ```ts
@@ -1570,27 +1960,34 @@ const bulkRemoveMap = async (configInput, ids) => {
 const getDBInfo = async (configInput) => {
 	const config = CouchConfig.parse(configInput);
 	const logger = createLogger(config);
-	const url = `${config.couch}`;
+	const url = createCouchDbUrl(config.couch);
 	let resp;
 	try {
-		resp = await needle("get", url, mergeNeedleOpts(config, {
-			json: true,
-			headers: { "Content-Type": "application/json" }
-		}));
+		resp = await fetchCouchJson({
+			auth: config.auth,
+			method: "GET",
+			operation: "getDBInfo",
+			request: config.request,
+			url
+		});
+		if (!isSuccessStatusCode("database", resp.statusCode)) {
+			logger.error(`Non-success status code received: ${resp.statusCode}`);
+			throw createResponseError({
+				body: resp.body,
+				defaultMessage: "Failed to fetch database info",
+				operation: "getDBInfo",
+				statusCode: resp.statusCode
+			});
+		}
 	} catch (err) {
 		logger.error("Error during get operation:", err);
-		RetryableError.handleNetworkError(err);
+		RetryableError.handleNetworkError(err, "getDBInfo");
 	}
 	if (!resp) {
 		logger.error("No response received from get request");
-		throw new RetryableError("no response", 503);
+		throw new RetryableError("Failed to fetch database info", 503, { operation: "getDBInfo" });
 	}
-	const result = resp.body;
-	if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
-		logger.warn(`Retryable status code received: ${resp.statusCode}`);
-		throw new RetryableError(result.reason ?? "retryable error", resp.statusCode);
-	}
-	return CouchDBInfo.parse(result);
+	return CouchDBInfo.parse(resp.body);
 };
 
 //#endregion
@@ -1686,7 +2083,7 @@ async function removeLock(configInput, docId, lockOptions) {
 
 //#endregion
 //#region schema/sugar/watch.mts
-const WatchOptions = z$1.object({
+const WatchOptions = z$1.strictObject({
 	include_docs: z$1.boolean().default(false),
 	maxRetries: z$1.number().describe("maximum number of retries before giving up"),
 	initialDelay: z$1.number().describe("initial delay between retries in milliseconds"),
@@ -1712,112 +2109,155 @@ function watchDocs(configInput, docIds, onChange, optionsInput = {}) {
 	const options = WatchOptions.parse(optionsInput);
 	const logger = createLogger(config);
 	const emitter = new EventEmitter();
+	const request = config.request;
 	let lastSeq = null;
 	let stopping = false;
+	let stopEndEmitted = false;
 	let retryCount = 0;
-	let currentRequest = null;
+	const lifecycleAbortController = new AbortController();
+	let currentAbortController = null;
 	const maxRetries = options.maxRetries || 10;
 	const initialDelay = options.initialDelay || 1e3;
 	const maxDelay = options.maxDelay || 3e4;
 	const _docIds = Array.isArray(docIds) ? docIds : [docIds];
-	if (_docIds.length === 0) throw new Error("docIds must be a non-empty array");
-	if (_docIds.length > 100) throw new Error("docIds must be an array of 100 or fewer elements");
+	if (_docIds.length === 0) throw new OperationError("docIds must be a non-empty array", { operation: "watchDocs" });
+	if (_docIds.length > 100) throw new OperationError("docIds must be an array of 100 or fewer elements", { operation: "watchDocs" });
+	const emitStopEnd = () => {
+		if (stopEndEmitted) return;
+		stopEndEmitted = true;
+		emitter.emit("end", { lastSeq });
+	};
+	const stopWatching = () => {
+		if (stopping) return;
+		stopping = true;
+		lifecycleAbortController.abort();
+		currentAbortController?.abort();
+		request?.signal?.removeEventListener("abort", handleExternalAbort);
+		emitStopEnd();
+		emitter.removeAllListeners();
+	};
+	const handleExternalAbort = () => {
+		logger.info(`Request signal aborted, stopping watcher for [${_docIds}]`);
+		stopWatching();
+	};
+	request?.signal?.addEventListener("abort", handleExternalAbort, { once: true });
 	const connect = async () => {
 		if (stopping) return;
 		const feed = "continuous";
 		const includeDocs = options.include_docs ?? false;
-		const ids = _docIds.join("\",\"");
-		const url = `${config.couch}/_changes?feed=${feed}&since=${lastSeq}&include_docs=${includeDocs}&filter=_doc_ids&doc_ids=["${ids}"]`;
-		const mergedOpts = mergeNeedleOpts(config, {
-			json: false,
-			headers: { "Content-Type": "application/json" },
-			parse_response: false
-		});
+		const url = createCouchPathUrl("_changes", config.couch);
+		url.searchParams.set("feed", feed);
+		url.searchParams.set("since", String(lastSeq));
+		url.searchParams.set("include_docs", String(includeDocs));
+		url.searchParams.set("filter", "_doc_ids");
+		url.searchParams.set("doc_ids", JSON.stringify(_docIds));
+		const abortController = new AbortController();
+		currentAbortController = abortController;
 		let buffer = "";
-		currentRequest = needle.get(url, mergedOpts);
-		currentRequest.on("data", (chunk) => {
-			buffer += chunk.toString();
-			const lines = buffer.split("\n");
-			buffer = lines.pop() || "";
-			for (const line of lines) if (line.trim()) try {
+		const processLine = (line) => {
+			if (!line.trim()) return;
+			try {
 				const change = JSON.parse(line);
-				if (!change.id) return null;
+				if (!change.id) return;
 				logger.debug(`Change detected, watching [${_docIds}]`, change);
 				lastSeq = change.seq || change.last_seq;
 				emitter.emit("change", change);
 			} catch (err) {
 				logger.error("Error parsing change:", err, "Line:", line);
 			}
-		});
-		currentRequest.on("response", (response) => {
+		};
+		try {
+			const response = await fetchCouchStream({
+				auth: config.auth,
+				method: "GET",
+				operation: "watchDocs",
+				url,
+				headers: { "Content-Type": "application/json" },
+				request,
+				signal: AbortSignal.any([abortController.signal, lifecycleAbortController.signal])
+			});
 			logger.debug(`Received response with status code, watching [${_docIds}]: ${response.statusCode}`);
 			if (RetryableError.isRetryableStatusCode(response.statusCode)) {
 				logger.warn(`Retryable status code received: ${response.statusCode}`);
-				currentRequest?.destroy();
-				handleReconnect();
-			} else retryCount = 0;
-		});
-		currentRequest.on("error", async (err) => {
-			if (stopping) {
+				abortController.abort();
+				await handleReconnect();
+				return;
+			}
+			if (!isSuccessStatusCode("changesFeed", response.statusCode)) {
+				emitter.emit("error", createResponseError({
+					defaultMessage: "Watch request failed",
+					operation: "watchDocs",
+					statusCode: response.statusCode
+				}));
+				return;
+			}
+			retryCount = 0;
+			if (!response.body) throw new RetryableError("Watch request failed", 503, { operation: "watchDocs" });
+			const reader = response.body.getReader();
+			const decoder = new TextDecoder();
+			while (!stopping) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				const lines = buffer.split("\n");
+				buffer = lines.pop() || "";
+				lines.forEach(processLine);
+			}
+			if (stopping || abortController.signal.aborted) return;
+			buffer += decoder.decode();
+			if (buffer.trim()) processLine(buffer);
+			logger.info("Stream completed. Last seen seq: ", lastSeq);
+			emitter.emit("end", { lastSeq });
+			if (!stopping) await handleReconnect();
+		} catch (err) {
+			if (stopping || abortController.signal.aborted) {
 				logger.info("stopping in progress, ignore stream error");
 				return;
 			}
-			logger.error(`Network error during stream, watching [${_docIds}]:`, err.toString());
+			logger.error(`Network error during stream, watching [${_docIds}]:`, String(err));
 			try {
-				RetryableError.handleNetworkError(err);
+				RetryableError.handleNetworkError(err, "watchDocs");
 			} catch (filteredError) {
 				if (filteredError instanceof RetryableError) {
 					logger.info(`Retryable error, watching [${_docIds}]:`, filteredError.toString());
-					handleReconnect();
+					await handleReconnect();
 				} else {
-					logger.error(`Non-retryable error, watching [${_docIds}]`, filteredError?.toString());
+					logger.error(`Non-retryable error, watching [${_docIds}]`, String(filteredError));
 					emitter.emit("error", filteredError);
 				}
 			}
-		});
-		currentRequest.on("end", () => {
-			if (buffer.trim()) try {
-				const change = JSON.parse(buffer);
-				logger.debug("Final change detected:", change);
-				emitter.emit("change", change);
-			} catch (err) {
-				logger.error("Error parsing final change:", err);
-			}
-			logger.info("Stream completed. Last seen seq: ", lastSeq);
-			emitter.emit("end", { lastSeq });
-			if (!stopping) handleReconnect();
-		});
+		}
 	};
 	const handleReconnect = async () => {
 		if (stopping || retryCount >= maxRetries) {
 			if (retryCount >= maxRetries) {
 				logger.error(`Max retries (${maxRetries}) reached, giving up`);
-				emitter.emit("error", /* @__PURE__ */ new Error("Max retries reached"));
+				emitter.emit("error", new OperationError("Watch retries exhausted", { operation: "watchDocs" }));
 			}
 			return;
 		}
 		const delay = Math.min(initialDelay * Math.pow(2, retryCount), maxDelay);
 		retryCount++;
 		logger.info(`Attempting to reconnect in ${delay}ms (attempt ${retryCount} of ${maxRetries})`);
-		await setTimeout$1(delay);
 		try {
-			connect();
+			await setTimeout$1(delay, void 0, { signal: lifecycleAbortController.signal });
+		} catch {
+			return;
+		}
+		try {
+			await connect();
 		} catch (err) {
 			logger.error("Error during reconnection:", err);
-			handleReconnect();
+			await handleReconnect();
 		}
 	};
-	connect();
 	emitter.on("change", onChange);
+	if (request?.signal?.aborted) stopWatching();
+	else connect();
 	return {
 		on: (event, listener) => emitter.on(event, listener),
 		removeListener: (event, listener) => emitter.removeListener(event, listener),
-		stop: () => {
-			stopping = true;
-			if (currentRequest) currentRequest.destroy();
-			emitter.emit("end", { lastSeq });
-			emitter.removeAllListeners();
-		}
+		stop: stopWatching
 	};
 }
 
@@ -1895,4 +2335,4 @@ function doBind(config) {
 }
 
 //#endregion
-export { QueryBuilder, bindConfig, bulkGet, bulkGetDictionary, bulkRemove, bulkRemoveMap, bulkSave, bulkSaveTransaction, createLock, createQuery, get, getAtRev, getDBInfo, patch, patchDangerously, put, query, queryStream, remove, removeLock, watchDocs, withRetry };
+export { ConflictError, HideABedError, NotFoundError, OperationError, QueryBuilder, RetryableError, ValidationError, bindConfig, bulkGet, bulkGetDictionary, bulkRemove, bulkRemoveMap, bulkSave, bulkSaveTransaction, createLock, createQuery, get, getAtRev, getDBInfo, patch, patchDangerously, put, query, queryStream, remove, removeLock, watchDocs, withRetry };