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

package/dist/esm/index.mjs

@@ -0,0 +1,1898 @@
+import z, { z as z$1 } from "zod";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import needle from "needle";
+import Chain from "stream-chain";
+import Parser from "stream-json/Parser.js";
+import Pick from "stream-json/filters/Pick.js";
+import StreamArray from "stream-json/streamers/StreamArray.js";
+import { EventEmitter } from "events";
+
+//#region impl/utils/queryBuilder.mts
+/**
+* A builder class for constructing CouchDB view query options.
+* Provides a fluent API for setting various query parameters.
+* @example
+* const queryOptions = new QueryBuilder()
+*   .limit(10)
+*   .include_docs()
+*   .startKey('someKey')
+*   .build();
+* @see SimpleViewOptions for the full list of options.
+*
+* @remarks
+* Each method corresponds to a CouchDB view option and returns the builder instance for chaining.
+*
+* @returns The constructed SimpleViewOptions object.
+*/
+var QueryBuilder = class {
+	#options = {};
+	descending(descending = true) {
+		this.#options.descending = descending;
+		return this;
+	}
+	endkey_docid(endkeyDocId) {
+		this.#options.endkey_docid = endkeyDocId;
+		return this;
+	}
+	/**
+	* Alias for endkey_docid
+	*/
+	end_key_doc_id(endkeyDocId) {
+		this.#options.endkey_docid = endkeyDocId;
+		return this;
+	}
+	endkey(endkey) {
+		this.#options.endkey = endkey;
+		return this;
+	}
+	/**
+	* Alias for endkey
+	*/
+	endKey(endkey) {
+		this.#options.endkey = endkey;
+		return this;
+	}
+	/**
+	* Alias for endkey
+	*/
+	end_key(endkey) {
+		this.#options.endkey = endkey;
+		return this;
+	}
+	group(group = true) {
+		this.#options.group = group;
+		return this;
+	}
+	group_level(level) {
+		this.#options.group_level = level;
+		return this;
+	}
+	include_docs(includeDocs = true) {
+		this.#options.include_docs = includeDocs;
+		return this;
+	}
+	inclusive_end(inclusiveEnd = true) {
+		this.#options.inclusive_end = inclusiveEnd;
+		return this;
+	}
+	key(key) {
+		this.#options.key = key;
+		return this;
+	}
+	keys(keys) {
+		this.#options.keys = keys;
+		return this;
+	}
+	limit(limit) {
+		this.#options.limit = limit;
+		return this;
+	}
+	reduce(reduce = true) {
+		this.#options.reduce = reduce;
+		return this;
+	}
+	skip(skip) {
+		this.#options.skip = skip;
+		return this;
+	}
+	sorted(sorted = true) {
+		this.#options.sorted = sorted;
+		return this;
+	}
+	stable(stable = true) {
+		this.#options.stable = stable;
+		return this;
+	}
+	startkey(startkey) {
+		this.#options.startkey = startkey;
+		return this;
+	}
+	/**
+	* Alias for startkey
+	*/
+	startKey(startkey) {
+		this.#options.startkey = startkey;
+		return this;
+	}
+	/**
+	* Alias for startkey
+	*/
+	start_key(startkey) {
+		this.#options.startkey = startkey;
+		return this;
+	}
+	startkey_docid(startkeyDocId) {
+		this.#options.startkey_docid = startkeyDocId;
+		return this;
+	}
+	/**
+	* Alias for startkey_docid
+	*/
+	start_key_doc_id(startkeyDocId) {
+		this.#options.startkey_docid = startkeyDocId;
+		return this;
+	}
+	update(update) {
+		this.#options.update = update;
+		return this;
+	}
+	update_seq(updateSeq = true) {
+		this.#options.update_seq = updateSeq;
+		return this;
+	}
+	/**
+	* Builds and returns the ViewOptions object.
+	*/
+	build() {
+		return { ...this.#options };
+	}
+};
+const createQuery = () => new QueryBuilder();
+
+//#endregion
+//#region schema/config.mts
+const anyArgs = z$1.array(z$1.any());
+const LoggerSchema = z$1.object({
+	error: z$1.function({
+		input: anyArgs,
+		output: z$1.void()
+	}).optional(),
+	warn: z$1.function({
+		input: anyArgs,
+		output: z$1.void()
+	}).optional(),
+	info: z$1.function({
+		input: anyArgs,
+		output: z$1.void()
+	}).optional(),
+	debug: z$1.function({
+		input: anyArgs,
+		output: z$1.void()
+	}).optional()
+}).or(z$1.function({
+	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 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 CouchConfig = z$1.strictObject({
+	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"),
+	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"),
+	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/errors.mts
+const RETRYABLE_STATUS_CODES = new Set([
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const NETWORK_ERROR_STATUS_MAP = {
+	ECONNREFUSED: 503,
+	ECONNRESET: 503,
+	ETIMEDOUT: 503,
+	ENETUNREACH: 503,
+	ENOTFOUND: 503,
+	EPIPE: 503,
+	EHOSTUNREACH: 503,
+	ESOCKETTIMEDOUT: 503
+};
+const isNetworkError = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.code === "string" && candidate.code in NETWORK_ERROR_STATUS_MAP;
+};
+/**
+* Error thrown when a requested CouchDB document cannot be found.
+*
+* @remarks
+* The `docId` property exposes the identifier that triggered the failure, which is
+* helpful for logging and retry strategies.
+*
+* @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);
+		this.name = "NotFoundError";
+		this.docId = docId;
+	}
+};
+/**
+* Error signalling that an operation can be retried due to transient conditions.
+*
+* @remarks
+* Use `RetryableError.isRetryableStatusCode` and `RetryableError.handleNetworkError`
+* to detect when a failure should trigger retry logic.
+*
+* @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);
+		this.name = "RetryableError";
+		this.statusCode = statusCode;
+	}
+	/**
+	* Determines whether the provided status code should be treated as retryable.
+	*
+	* @param statusCode - HTTP status code returned by CouchDB.
+	*
+	* @returns `true` if the status code is considered retryable; otherwise `false`.
+	*/
+	static isRetryableStatusCode(statusCode) {
+		if (typeof statusCode !== "number") return false;
+		return RETRYABLE_STATUS_CODES.has(statusCode);
+	}
+	/**
+	* Converts low-level network errors into {@link RetryableError} instances when possible.
+	*
+	* @param err - The error thrown by the underlying HTTP client.
+	*
+	* @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);
+		}
+		throw err;
+	}
+};
+function isConflictError(err) {
+	if (typeof err !== "object" || err === null) return false;
+	return err.statusCode === 409;
+}
+
+//#endregion
+//#region impl/retry.mts
+/**
+* Wrap an async-capable function with retry semantics that respect {@link RetryableError}.
+* @typeParam Fn - The function signature to decorate with retry handling.
+* @param fn The function to invoke with retry support.
+* @param options Retry tuning parameters.
+* @returns A function mirroring `fn` that automatically retries on {@link RetryableError}.
+*/
+function withRetry(fn, options = {}) {
+	const { maxRetries = 3, initialDelay = 1e3, backoffFactor = 2, maxDelay = 3e4 } = options;
+	return async (...args) => {
+		let delay = initialDelay;
+		for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+			return await fn(...args);
+		} catch (error) {
+			if (!(error instanceof RetryableError)) throw error;
+			if (attempt === maxRetries) throw error;
+			await setTimeout$1(Math.min(delay, maxDelay));
+			delay *= backoffFactor;
+		}
+		throw new RetryableError("withRetry exhausted retry attempts without resolving the operation");
+	};
+}
+
+//#endregion
+//#region impl/utils/logger.mts
+const noop = () => {};
+const createConsoleLogger = () => ({
+	error: (...args) => console.error(...args),
+	warn: (...args) => console.warn(...args),
+	info: (...args) => console.info(...args),
+	debug: (...args) => console.debug(...args)
+});
+const createNoopLogger = () => ({
+	error: noop,
+	warn: noop,
+	info: noop,
+	debug: noop
+});
+function createLogger(config) {
+	if (config["~normalizedLogger"]) return config["~normalizedLogger"];
+	if (!config.logger) {
+		const normalized$1 = config.useConsoleLogger ? createConsoleLogger() : createNoopLogger();
+		config["~normalizedLogger"] = normalized$1;
+		return normalized$1;
+	}
+	if (typeof config.logger === "function") {
+		const loggerFn = config.logger;
+		const normalized$1 = {
+			error: (...args) => loggerFn("error", ...args),
+			warn: (...args) => loggerFn("warn", ...args),
+			info: (...args) => loggerFn("info", ...args),
+			debug: (...args) => loggerFn("debug", ...args)
+		};
+		config["~normalizedLogger"] = normalized$1;
+		return normalized$1;
+	}
+	const loggerObj = config.logger;
+	const normalized = {
+		error: loggerObj.error ?? noop,
+		warn: loggerObj.warn ?? noop,
+		info: loggerObj.info ?? noop,
+		debug: loggerObj.debug ?? noop
+	};
+	config["~normalizedLogger"] = normalized;
+	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
+/**
+* Default schema for a returned CouchDB document if no validation schema is provided.
+*/
+const CouchDoc = z$1.looseObject({
+	_id: z$1.string().describe("the couch doc id"),
+	_rev: z$1.string().optional().nullish().describe("the doc revision"),
+	_deleted: z$1.boolean().optional().describe("is the doc deleted")
+});
+/**
+* Default schema for a CouchDB view row if no validation schema is provided.
+*/
+const ViewRow = z$1.object({
+	id: z$1.string().optional(),
+	key: z$1.any().nullish(),
+	value: z$1.any().nullish(),
+	doc: CouchDoc.nullish(),
+	error: z$1.string().optional().describe("usually not_found, if something is wrong with this doc")
+});
+/**
+* Response type for a CouchDB view query if no validation schemas are provided.
+*/
+const ViewQueryResponse = z$1.object({
+	total_rows: z$1.number().nonnegative().optional().describe("total rows in the view"),
+	offset: z$1.number().nonnegative().optional().describe("the offset of the first row in this result set"),
+	error: z$1.string().optional().describe("if something is wrong"),
+	rows: z$1.array(ViewRow).optional().describe("the rows returned by the view"),
+	update_seq: z$1.number().optional().describe("the update sequence of the database at the time of the query")
+});
+/**
+* CouchDB _bulk_docs response schema
+*/
+const BulkSaveResponse = z$1.array(z$1.object({
+	ok: z$1.boolean().nullish(),
+	id: z$1.string().nullish(),
+	rev: z$1.string().nullish(),
+	error: z$1.string().nullish().describe("if an error occurred, one word reason, eg conflict"),
+	reason: z$1.string().nullish().describe("a full error message")
+}));
+const CouchPutResponse = z$1.object({
+	ok: z$1.boolean().optional().describe("did the request succeed"),
+	error: z$1.string().optional().describe("the error message, if did not succeed"),
+	statusCode: z$1.number(),
+	id: z$1.string().optional().describe("the couch doc id"),
+	rev: z$1.string().optional().describe("the new rev of the doc")
+});
+const CouchDBInfo = z$1.looseObject({
+	cluster: z$1.object({
+		n: z$1.number().describe("Replicas. The number of copies of every document.").optional(),
+		q: z$1.number().describe("Shards. The number of range partitions.").optional(),
+		r: z$1.number().describe("Read quorum. The number of consistent copies of a document that need to be read before a successful reply.").optional(),
+		w: z$1.number().describe("Write quorum. The number of copies of a document that need to be written before a successful reply.").optional()
+	}).optional(),
+	compact_running: z$1.boolean().describe("Set to true if the database compaction routine is operating on this database.").optional(),
+	db_name: z$1.string().describe("The name of the database."),
+	disk_format_version: z$1.number().describe("The version of the physical format used for the data when it is stored on disk.").optional(),
+	doc_count: z$1.number().describe("A count of the documents in the specified database.").optional(),
+	doc_del_count: z$1.number().describe("Number of deleted documents").optional(),
+	instance_start_time: z$1.string().optional(),
+	purge_seq: z$1.string().describe("An opaque string that describes the purge state of the database. Do not rely on this string for counting the number of purge operations.").optional(),
+	sizes: z$1.object({
+		active: z$1.number().describe("The size of live data inside the database, in bytes.").optional(),
+		external: z$1.number().describe("The uncompressed size of database contents in bytes.").optional(),
+		file: z$1.number().describe("The size of the database file on disk in bytes. Views indexes are not included in the calculation.").optional()
+	}).optional(),
+	update_seq: z$1.string().or(z$1.number()).describe("An opaque string that describes the state of the database. Do not rely on this string for counting the number of updates.").optional(),
+	props: z$1.object({ partitioned: z$1.boolean().describe("If present and true, this indicates that the database is partitioned.").optional() }).optional()
+});
+
+//#endregion
+//#region impl/utils/parseRows.mts
+async function parseRows(rows, options) {
+	if (!Array.isArray(rows)) throw new Error("invalid rows format");
+	const isFinalRow = (row) => row !== "skip";
+	return (await Promise.all(rows.map(async (row) => {
+		try {
+			/**
+			* If no doc is present, parse without doc validation.
+			* This allows handling of not-found documents or rows without docs.
+			*/
+			if (row.doc == null) {
+				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;
+					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;
+					parsedRow.value = parsedValue$1.value;
+				}
+				return parsedRow;
+			}
+			let parsedDoc = row.doc;
+			let parsedKey = row.key;
+			let parsedValue = row.value;
+			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 parsedDoc = parsedDocRes.value;
+			}
+			if (options.keySchema) {
+				const parsedKeyRes = await options.keySchema["~standard"].validate(row.key);
+				if (parsedKeyRes.issues) throw parsedKeyRes.issues;
+				else parsedKey = parsedKeyRes.value;
+			}
+			if (options.valueSchema) {
+				const parsedValueRes = await options.valueSchema["~standard"].validate(row.value);
+				if (parsedValueRes.issues) throw parsedValueRes.issues;
+				else parsedValue = parsedValueRes.value;
+			}
+			return {
+				...row,
+				doc: parsedDoc,
+				key: parsedKey,
+				value: parsedValue
+			};
+		} catch (e) {
+			if (options.onInvalidDoc === "skip") return "skip";
+			else throw e;
+		}
+	}))).filter(isFinalRow);
+}
+
+//#endregion
+//#region impl/bulkGet.mts
+/**
+* Executes the bulk get operation against CouchDB.
+*
+* @param _config CouchDB configuration
+* @param ids Array of document IDs to retrieve
+* @param includeDocs Whether to include documents in the response
+*
+* @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.
+*/
+async function executeBulkGet(_config, ids, includeDocs) {
+	const configParseResult = CouchConfig.safeParse(_config);
+	const logger = createLogger(_config);
+	logger.info(`Starting bulk get for ${ids.length} documents`);
+	if (!configParseResult.success) {
+		logger.error("Invalid configuration provided for bulk get", configParseResult.error);
+		throw configParseResult.error;
+	}
+	const config = configParseResult.data;
+	const url = `${config.couch}/_all_docs${includeDocs ? "?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);
+		if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
+			logger.warn(`Retryable status code received: ${resp.statusCode}`);
+			throw new RetryableError("retryable error during bulk get", resp.statusCode);
+		}
+		if (resp.statusCode !== 200) {
+			logger.error(`Unexpected status code: ${resp.statusCode}`);
+			throw new Error("could not fetch");
+		}
+		return resp.body;
+	} catch (err) {
+		logger.error("Network error during bulk get:", err);
+		RetryableError.handleNetworkError(err);
+	}
+}
+/**
+* Bulk get documents by IDs with options.
+*
+* @template DocSchema - schema (StandardSchemaV1) used to validate each returned document, if provided.
+*
+* @param config - CouchDB configuration data that is validated before use.
+* @param ids - Array of document IDs to retrieve.
+* @param options - Options for bulk get operation, including whether to include documents and validation schema.
+*
+* @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.
+*/
+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");
+	const docSchema = options.validate?.docSchema || CouchDoc;
+	const rows = await parseRows(body.rows, {
+		onInvalidDoc: options.validate?.onInvalidDoc,
+		docSchema
+	});
+	return {
+		...body,
+		rows
+	};
+}
+/**
+* Bulk get documents by IDs.
+*
+* @remarks
+* By default, documents are included in the response. To exclude documents, set `includeDocs` to `false`.
+* When `includeDocs` is `true`, you can provide a schema (StandardSchemaV1) to validate the documents.
+* When a schema is provided, you can specify how to handle invalid documents using `onInvalidDoc` option.
+* `onInvalidDoc` can be set to `'throw'` (default) to throw an error on invalid documents, or `'skip'` to omit them from the results.
+*
+* @template DocSchema - schema (StandardSchemaV1) used to validate each returned document, if provided.
+*
+* @param config - CouchDB configuration data that is validated before use.
+* @param ids - Array of document IDs to retrieve.
+* @param options - Options for bulk get operation, including whether to include documents and validation schema.
+*
+* @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.
+*/
+async function bulkGet(config, ids, options = {}) {
+	return _bulkGetWithOptions(config, ids, {
+		includeDocs: options.includeDocs,
+		validate: options?.validate
+	});
+}
+/**
+* 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"]>.
+*
+* @param config - CouchDB configuration data that is validated before use.
+* @param ids - Array of document IDs to retrieve.
+* @param options - Options for bulk get operation, including validation schema.
+*
+* @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.
+*/
+async function bulkGetDictionary(config, ids, options) {
+	const response = await bulkGet(config, ids, {
+		includeDocs: true,
+		...options
+	});
+	const results = {
+		found: {},
+		notFound: {}
+	};
+	for (const row of response.rows ?? []) {
+		const key = typeof row.key === "string" ? row.key : row.id;
+		if (!key) continue;
+		if (row.error || !row.doc) {
+			results.notFound[key] = row;
+			continue;
+		}
+		const doc = row.doc;
+		const docId = typeof doc?._id === "string" ? doc._id : row.id;
+		if (!docId) {
+			results.notFound[key] = row;
+			continue;
+		}
+		results.found[docId] = doc;
+	}
+	return results;
+}
+
+//#endregion
+//#region impl/get.mts
+const ValidSchema = 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({
+	rev: z$1.string().optional().describe("the couch doc revision"),
+	validate: z$1.object({ docSchema: ValidSchema.optional() }).optional().describe("optional document validation rules")
+});
+async function _getWithOptions(config, id, options) {
+	const parsedOptions = CouchGetOptions.parse({
+		rev: options.rev,
+		validate: options.validate
+	});
+	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" }
+	});
+	logger.info(`Getting document with id: ${id}, rev ${rev ?? "latest"}`);
+	try {
+		const resp = await needle("get", url, null, requestOptions);
+		if (!resp) {
+			logger.error("No response received from get request");
+			throw new RetryableError("no response", 503);
+		}
+		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;
+		}
+		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";
+			logger.error(`Unexpected status code: ${resp.statusCode}`);
+			throw new Error(reason);
+		}
+		const typedDoc = await (parsedOptions.validate?.docSchema ?? CouchDoc)["~standard"].validate(body);
+		if (typedDoc.issues) throw typedDoc.issues;
+		logger.info(`Successfully retrieved document: ${id}, rev ${rev ?? "latest"}`);
+		return typedDoc.value;
+	} catch (err) {
+		logger.error("Error during get operation:", err);
+		RetryableError.handleNetworkError(err);
+	}
+}
+async function get(config, id, options) {
+	return _getWithOptions(config, id, options ?? {});
+}
+async function getAtRev(config, id, rev, options) {
+	return _getWithOptions(config, id, {
+		...options,
+		rev
+	});
+}
+
+//#endregion
+//#region schema/couch/couch.input.schema.ts
+const ViewOptions = z.object({
+	descending: z.boolean().optional().describe("sort results descending"),
+	endkey_docid: z.string().optional().describe("stop returning records when this document ID is reached"),
+	endkey: z.any().optional(),
+	group_level: z.number().positive().optional().describe("group the results at this level"),
+	group: z.boolean().optional().describe("group the results"),
+	include_docs: z.boolean().optional().describe("join the id to the doc and return it"),
+	inclusive_end: z.boolean().optional().describe("whether the endkey is included in the result, default true"),
+	key: z.any().optional(),
+	keys: z.array(z.any()).optional(),
+	limit: z.number().nonnegative().optional().describe("limit the results to this many rows"),
+	reduce: z.boolean().optional().describe("reduce the results"),
+	skip: z.number().nonnegative().optional().describe("skip this many rows"),
+	sorted: z.boolean().optional().describe("sort returned rows, default true"),
+	stable: z.boolean().optional().describe("ensure the view index is not updated during the query, default false"),
+	startkey: z.any().optional(),
+	startkey_docid: z.string().optional().describe("start returning records when this document ID is reached"),
+	update: z.enum([
+		"true",
+		"false",
+		"lazy"
+	]).optional().describe("whether to update the view index before returning results, default true"),
+	update_seq: z.boolean().optional().describe("include the update sequence in the result")
+}).describe("base options for a CouchDB view query");
+
+//#endregion
+//#region impl/utils/queryString.mts
+const KEYS_TO_QUOTE = [
+	"endkey_docid",
+	"endkey",
+	"key",
+	"keys",
+	"startkey",
+	"startkey_docid",
+	"update"
+];
+/**
+* Serialize CouchDB view options into a URL-safe query string, quoting values CouchDB expects as JSON.
+* @param options The view options to serialize
+* @param params The list of option keys that require JSON quoting
+* @returns The serialized query string
+*/
+function queryString(options = {}) {
+	const searchParams = new URLSearchParams();
+	const parsedOptions = ViewOptions.parse(options);
+	Object.entries(parsedOptions).forEach(([key, rawValue]) => {
+		let value = rawValue;
+		if (KEYS_TO_QUOTE.includes(key)) {
+			if (typeof value === "string") value = `"${value}"`;
+			if (Array.isArray(value)) value = "[" + value.map((i) => {
+				if (i === null) return "null";
+				if (typeof i === "string") return `"${i}"`;
+				if (typeof i === "object" && Object.keys(i).length === 0) return "{}";
+				if (typeof i === "object") return JSON.stringify(i);
+				return i;
+			}).join(",") + "]";
+		}
+		searchParams.set(key, String(value));
+	});
+	return searchParams.toString();
+}
+
+//#endregion
+//#region impl/stream.mts
+/**
+* Execute a CouchDB view query and stream rows as they are received.
+* @param rawConfig CouchDB configuration
+* @param view The CouchDB view to query
+* @param options Query options
+* @param onRow Callback invoked for each row received
+*/
+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();
+			}
+		});
+		request.on("error", (err) => {
+			logger.error("Network error during stream query:", err);
+			parserPipeline.destroy(err);
+			try {
+				RetryableError.handleNetworkError(err);
+			} catch (retryErr) {
+				settleReject(retryErr);
+				return;
+			} finally {
+				settleReject(err);
+			}
+		});
+		request.pipe(parserPipeline);
+	});
+}
+
+//#endregion
+//#region impl/put.mts
+const put = async (configInput, doc) => {
+	const config = CouchConfig.parse(configInput);
+	const logger = createLogger(config);
+	const url = `${config.couch}/${doc._id}`;
+	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);
+	} catch (err) {
+		logger.error("Error during put operation:", err);
+		RetryableError.handleNetworkError(err);
+	}
+	if (!resp) {
+		logger.error("No response received from put request");
+		throw new RetryableError("no response", 503);
+	}
+	const result = 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);
+	}
+	if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
+		logger.warn(`Retryable status code received: ${resp.statusCode}`);
+		throw new RetryableError(result.reason || "retryable error", resp.statusCode);
+	}
+	logger.info(`Successfully saved document: ${doc._id}`);
+	return CouchPutResponse.parse(result);
+};
+
+//#endregion
+//#region impl/patch.mts
+const PatchProperties = z$1.looseObject({ _rev: z$1.string("_rev is required for patch operations") }).describe("Patch payload with _rev");
+/**
+* Patch a CouchDB document by merging provided properties.
+* Validates that the _rev matches before applying the patch.
+*
+* @param configInput - CouchDB configuration
+* @param id - Document ID to patch
+* @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
+*/
+const patch = async (configInput, id, _properties) => {
+	const config = CouchConfig.parse(configInput);
+	const properties = PatchProperties.parse(_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 updatedDoc = {
+		...doc,
+		...properties
+	};
+	logger.debug("Merged document:", updatedDoc);
+	const result = await put(config, updatedDoc);
+	logger.info(`Successfully patched document ${id}, rev: ${result.rev}`);
+	return result;
+};
+/**
+* Patch a CouchDB document by merging provided properties.
+* This function will retry on conflicts using an exponential backoff strategy.
+*
+* @remarks patchDangerously can clobber data. It will retry even if a conflict happens. There are some use cases for this, but you have been warned, hence the name.
+*
+* @param configInput - CouchDB configuration
+* @param id - Document ID to patch
+* @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
+*/
+const patchDangerously = async (configInput, id, properties) => {
+	const config = CouchConfig.parse(configInput);
+	const logger = createLogger(config);
+	const maxRetries = config.maxRetries || 5;
+	let delay = config.initialDelay || 1e3;
+	let attempts = 0;
+	logger.info(`Starting patch operation for document ${id}`);
+	logger.debug("Patch properties:", properties);
+	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 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`);
+		} 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"
+				};
+			}
+			attempts++;
+			if (attempts > maxRetries) {
+				const error = `Failed to patch after ${maxRetries} attempts: ${err}`;
+				logger.error(error);
+				return {
+					ok: false,
+					statusCode: 500,
+					error
+				};
+			}
+			logger.warn(`Error during patch attempt ${attempts}: ${err}`);
+			await setTimeout$1(delay);
+			logger.debug(`Retrying after ${delay}ms`);
+		}
+	}
+};
+
+//#endregion
+//#region impl/query.mts
+/**
+* Executes a CouchDB view query with optional schema validation and automatic handling
+* of HTTP method selection, query string construction, and retryable errors.
+*
+* @remarks
+* When using the validation feature, each row in the response will be validated against the provided
+* Types will be inferred from the StandardSchemaV1 supplied in the `options.validate` object.
+*
+* @template DocSchema - StandardSchemaV1 used to validate each returned `doc`, if provided.
+* @template KeySchema - StandardSchemaV1 used to validate each row `key`, if provided.
+* @template ValueSchema - StandardSchemaV1 used to validate each row `value`, if provided.
+*
+* @param _config - CouchDB configuration data that is validated before use.
+* @param view - Fully qualified design document and view identifier (e.g., `_design/foo/_view/bar`).
+* @param options - CouchDB view options, including optional validation schemas.
+*
+* @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.
+*/
+async function query(_config, view, options = {}) {
+	const configParseResult = CouchConfig.safeParse(_config);
+	const logger = createLogger(_config);
+	logger.info(`Starting view query: ${view}`);
+	logger.debug("Query options:", ViewOptions.parse(options || {}));
+	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 payload = null;
+	const mergedOpts = mergeNeedleOpts(config, {
+		json: true,
+		headers: { "Content-Type": "application/json" }
+	});
+	if (typeof options.keys !== "undefined") {
+		const MAX_URL_LENGTH = 2e3;
+		const _options = structuredClone(options);
+		delete _options.keys;
+		qs = queryString(_options);
+		const keysAsString = `keys=${JSON.stringify(options.keys)}`;
+		if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) {
+			method = "get";
+			if (qs.length > 0) qs += "&";
+			else qs = "";
+			qs += keysAsString;
+		} else {
+			method = "post";
+			payload = { keys: options.keys };
+		}
+	}
+	logger.debug("Generated query string:", qs);
+	const url = `${config.couch}/${view}?${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);
+	} catch (err) {
+		logger.error("Network error during query:", err);
+		RetryableError.handleNetworkError(err);
+	}
+	if (!results) {
+		logger.error("No response received from query request");
+		throw new RetryableError("no response", 503);
+	}
+	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 (options.validate && body.rows) body.rows = await parseRows(body.rows, options.validate);
+	logger.info(`Successfully executed view query: ${view}`);
+	logger.debug("Query response:", body);
+	return body;
+}
+
+//#endregion
+//#region impl/utils/trackedEmitter.mts
+const setupEmitter = (config) => {
+	if (!config["~emitter"]) return { emit: async () => {} };
+	return config["~emitter"];
+};
+
+//#endregion
+//#region impl/utils/transactionErrors.mts
+var TransactionSetupError = class extends Error {
+	details;
+	constructor(message, details = {}) {
+		super(message);
+		this.name = "TransactionSetupError";
+		this.details = details;
+	}
+};
+var TransactionVersionConflictError = class extends Error {
+	conflictingIds;
+	constructor(conflictingIds) {
+		super(`Revision mismatch for documents: ${conflictingIds.join(", ")}`);
+		this.name = "TransactionVersionConflictError";
+		this.conflictingIds = conflictingIds;
+	}
+};
+var TransactionBulkOperationError = class extends Error {
+	failedDocs;
+	constructor(failedDocs) {
+		super(`Failed to save documents: ${failedDocs.map((d) => d.id).join(", ")}`);
+		this.name = "TransactionBulkOperationError";
+		this.failedDocs = failedDocs;
+	}
+};
+var TransactionRollbackError = class extends Error {
+	originalError;
+	rollbackResults;
+	constructor(message, originalError, rollbackResults) {
+		super(message);
+		this.name = "TransactionRollbackError";
+		this.originalError = originalError;
+		this.rollbackResults = rollbackResults;
+	}
+};
+
+//#endregion
+//#region impl/bulkSave.mts
+/**
+* Bulk saves documents to CouchDB using the _bulk_docs endpoint.
+*
+* @see
+* https://docs.couchdb.org/en/stable/api/database/bulk-api.html#db-bulk-docs
+*
+* @param {CouchConfigInput} config - The CouchDB configuration.
+* @param {CouchDocInput[]} docs - An array of documents to save.
+* @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.
+*/
+const bulkSave = async (config, docs) => {
+	const logger = createLogger(config);
+	if (docs == null || !docs.length) {
+		logger.error("bulkSave called with no docs");
+		throw new Error("no docs provided");
+	}
+	logger.info(`Starting bulk save of ${docs.length} documents`);
+	const url = `${config.couch}/_bulk_docs`;
+	const body = { docs };
+	const mergedOpts = mergeNeedleOpts(config, {
+		json: true,
+		headers: { "Content-Type": "application/json" }
+	});
+	let resp;
+	try {
+		resp = await needle("post", url, body, mergedOpts);
+	} catch (err) {
+		logger.error("Network error during bulk save:", err);
+		RetryableError.handleNetworkError(err);
+	}
+	if (!resp) {
+		logger.error("No response received from bulk save request");
+		throw new RetryableError("no response", 503);
+	}
+	if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
+		logger.warn(`Retryable status code received: ${resp.statusCode}`);
+		throw new RetryableError("retryable error during bulk save", resp.statusCode);
+	}
+	if (resp.statusCode !== 201) {
+		logger.error(`Unexpected status code: ${resp.statusCode}`);
+		throw new Error("could not save");
+	}
+	const results = resp?.body || [];
+	return BulkSaveResponse.parse(results);
+};
+/**
+* Performs a bulk save of documents within a transaction context.
+*
+* @remarks
+* This operation ensures that either all documents are saved successfully, or none are, maintaining data consistency.
+* If any document fails to save, the operation will attempt to roll back all changes.
+*
+* The transactionId has to be unique for the lifetime of the app. It is used to prevent two processes from executing the same transaction. It is up to you to craft a transactionId that uniquely represents this transaction, and that also is the same if another process tries to generate it.
+*
+* Exceptions to handle:
+*
+* `TransactionSetupError` Thrown if the transaction document cannot be created. Usually because it already exists
+* `TransactionVersionConflictError` Thrown if there are version conflicts with existing documents.
+* `TransactionBulkOperationError` Thrown if the bulk save operation fails for some documents.
+* `TransactionRollbackError` Thrown if the rollback operation fails after a transaction failure.
+*
+* @example
+* ```ts
+* const docsToSave = [
+*  { _id: 'doc1', foo: 'bar' },
+*  { _id: 'doc2', foo: 'baz' }
+* ];
+*
+* try {
+*  const results = await bulkSaveTransaction(config, 'unique-transaction-id', docsToSave);
+*  console.log('Bulk save successful:', results);
+*  } catch (error) {
+*  console.error('Bulk save transaction failed:', error);
+* }
+* ```
+*
+* @param {CouchConfigInput} config - The CouchDB configuration.
+* @param {string} transactionId - A unique identifier for the transaction.
+* @param {CouchDocInput[]} docs - An array of documents to save.
+* @returns {Promise<BulkSaveResponse>} - The transaction save results.
+* @throws {TransactionSetupError} When the transaction document cannot be created.
+* @throws {TransactionVersionConflictError} When there are version conflicts with existing documents.
+* @throws {TransactionBulkOperationError} When the bulk save operation fails for some documents.
+* @throws {TransactionRollbackError} When the rollback operation fails after a transaction failure.
+*/
+const bulkSaveTransaction = async (config, transactionId, docs) => {
+	const emitter = setupEmitter(config);
+	const logger = createLogger(config);
+	const retryOptions = {
+		maxRetries: config.maxRetries ?? 10,
+		initialDelay: config.initialDelay ?? 1e3,
+		backoffFactor: config.backoffFactor ?? 2
+	};
+	const _put = config.bindWithRetry ? withRetry(put.bind(null, config), retryOptions) : put.bind(null, config);
+	logger.info(`Starting bulk save transaction ${transactionId} for ${docs.length} documents`);
+	const transactionDoc = {
+		_id: `txn:${transactionId}`,
+		_rev: null,
+		type: "transaction",
+		status: "pending",
+		changes: docs,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	let transactionResponse = await _put(transactionDoc);
+	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);
+	/** @type {string[]} */
+	const revErrors = [];
+	docs.forEach((d) => {
+		if (!d._id) return;
+		if (existingDocs.found[d._id] && existingDocs.found[d._id]._rev !== d._rev) revErrors.push(d._id);
+		if (existingDocs.notFound[d._id] && d._rev) revErrors.push(d._id);
+	});
+	if (revErrors.length > 0) throw new TransactionVersionConflictError(revErrors);
+	logger.debug("Checked document revisions:", existingDocs);
+	await emitter.emit("transaction-revs-checked", existingDocs);
+	const providedDocsById = {};
+	docs.forEach((d) => {
+		if (!d._id) return;
+		providedDocsById[d._id] = d;
+	});
+	const newDocsToRollback = [];
+	const potentialExistingDocsToRollback = [];
+	const failedDocs = [];
+	try {
+		logger.info("Transaction started:", transactionDoc);
+		await emitter.emit("transaction-started", transactionDoc);
+		const results = await bulkSave(config, docs);
+		logger.info("Transaction updates applied:", results);
+		await emitter.emit("transaction-updates-applied", results);
+		results.forEach((r) => {
+			if (!r.id) return;
+			if (!r.error) {
+				if (existingDocs.notFound[r.id]) newDocsToRollback.push(r);
+				if (existingDocs.found[r.id]) potentialExistingDocsToRollback.push(r);
+			} else failedDocs.push(r);
+		});
+		if (failedDocs.length > 0) throw new TransactionBulkOperationError(failedDocs);
+		transactionDoc.status = "completed";
+		transactionDoc._rev = transactionResponse.rev;
+		transactionResponse = await _put(transactionDoc);
+		logger.info("Transaction completed:", transactionDoc);
+		await emitter.emit("transaction-completed", {
+			transactionResponse,
+			transactionDoc
+		});
+		if (transactionResponse.statusCode !== 201) logger.error("Failed to update transaction status to completed");
+		return results;
+	} catch (error) {
+		logger.error("Transaction failed, attempting rollback:", error);
+		const toRollback = [];
+		potentialExistingDocsToRollback.forEach((row) => {
+			if (!row.id || !row.rev) return;
+			const doc = existingDocs.found[row.id];
+			doc._rev = row.rev;
+			toRollback.push(doc);
+		});
+		newDocsToRollback.forEach((d) => {
+			if (!d.id || !d.rev) return;
+			const before = JSON.parse(JSON.stringify(providedDocsById[d.id]));
+			before._rev = d.rev;
+			before._deleted = true;
+			toRollback.push(before);
+		});
+		const bulkRollbackResult = await bulkSave(config, toRollback);
+		let status = "rolled_back";
+		bulkRollbackResult.forEach((r) => {
+			if (r.error) status = "rollback_failed";
+		});
+		logger.warn("Transaction rolled back:", {
+			bulkRollbackResult,
+			status
+		});
+		await emitter.emit("transaction-rolled-back", {
+			bulkRollbackResult,
+			status
+		});
+		transactionDoc.status = status;
+		transactionDoc._rev = transactionResponse.rev || null;
+		transactionResponse = await _put(transactionDoc);
+		logger.warn("Transaction rollback status updated:", transactionDoc);
+		await emitter.emit("transaction-rolled-back-status", {
+			transactionResponse,
+			transactionDoc
+		});
+		if (transactionResponse.statusCode !== 201) logger.error("Failed to update transaction status to rolled_back");
+		throw new TransactionRollbackError("Transaction failed and rollback was unsuccessful", error, bulkRollbackResult);
+	}
+};
+
+//#endregion
+//#region impl/remove.mts
+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" }
+	});
+	logger.info(`Deleting document with id: ${id}`);
+	let resp;
+	try {
+		resp = await needle("delete", url, null, mergedOpts);
+	} catch (err) {
+		logger.error("Error during delete operation:", err);
+		RetryableError.handleNetworkError(err);
+	}
+	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 = {};
+	}
+	else result = 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);
+	}
+	if (resp.statusCode !== 200) {
+		logger.error(`Unexpected status code: ${resp.statusCode}`);
+		throw new Error(result.reason || "failed");
+	}
+	logger.info(`Successfully deleted document: ${id}`);
+	return CouchPutResponse.parse(result);
+};
+
+//#endregion
+//#region impl/bulkRemove.mts
+/**
+* Removes multiple documents from a CouchDB database using the _bulk_docs endpoint.
+* It first retrieves the documents by their IDs, marks them as deleted, and then
+* sends them back to the database for deletion.
+*
+* See https://docs.couchdb.org/en/stable/api/database/bulk-api.html#post--db-_bulk_docs
+*
+* @param configInput - The CouchDB configuration input.
+* @param ids - An array of document IDs to be removed.
+* @returns A promise that resolves to an array of results from the bulk delete operation.
+*
+* @example
+* ```ts
+* const config: CouchConfigInput = {
+*   couch: 'http://localhost:5984/mydb',
+*   useConsoleLogger: true
+* };
+* const idsToRemove = ['doc1', 'doc2', 'doc3'];
+* const results = await bulkRemove(config, idsToRemove);
+* console.log(results);
+* ```
+*
+* @throws Will throw an error if the provided configuration is invalid or if the bulk delete operation fails.
+*/
+const bulkRemove = async (configInput, ids) => {
+	const config = CouchConfig.parse(configInput);
+	const logger = createLogger(config);
+	logger.info(`Starting bulk remove for ${ids.length} documents`);
+	const resp = await bulkGet(config, ids);
+	const toRemove = [];
+	resp.rows?.forEach((row) => {
+		if (!row.doc) return;
+		try {
+			const d = CouchDoc.parse(row.doc);
+			d._deleted = true;
+			toRemove.push(d);
+		} catch (e) {
+			logger.warn(`Invalid document structure in bulk remove: ${row.id}`, e);
+		}
+	});
+	if (!toRemove.length) return [];
+	return await bulkSave(config, toRemove);
+};
+/**
+* Removes multiple documents from a CouchDB database by their IDs using individual delete operations.
+* It first retrieves the documents to get their revision IDs, then deletes each document one by one.
+*
+* See https://docs.couchdb.org/en/stable/api/document/common.html#delete--db-docid
+*
+* @param configInput - The CouchDB configuration input.
+* @param ids - An array of document IDs to be removed.
+* @returns A promise that resolves to an array of results from the individual delete operations.
+*
+* @example
+* ```ts
+* const config: CouchConfigInput = {
+*   couch: 'http://localhost:5984/mydb',
+*   useConsoleLogger: true
+* };
+* const idsToRemove = ['doc1', 'doc2', 'doc3'];
+* const results = await bulkRemoveMap(config, idsToRemove);
+* console.log(results);
+* ```
+*
+* @throws Will throw an error if the provided configuration is invalid or if any delete operation fails.
+*/
+const bulkRemoveMap = async (configInput, ids) => {
+	const config = CouchConfig.parse(configInput);
+	const logger = createLogger(config);
+	logger.info(`Starting bulk remove map for ${ids.length} documents`);
+	const { rows } = await bulkGet(config, ids, { includeDocs: false });
+	const results = [];
+	for (const row of rows || []) try {
+		if (!row.value?.rev) throw new Error(`no rev found for doc ${row.id}`);
+		if (!row.id) throw new Error(`no id found for doc ${row}`);
+		const result = await remove(config, row.id, row.value.rev);
+		results.push(result);
+	} catch (e) {
+		logger.warn(`Error removing a doc in bulk remove map: ${row.id}`, e);
+	}
+	return results;
+};
+
+//#endregion
+//#region impl/getDBInfo.mts
+/**
+* Fetches and returns CouchDB database information.
+*
+* @see {@link https://docs.couchdb.org/en/stable/api/database/common.html#get--db | CouchDB API Documentation}
+*
+* @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.
+*
+* @example
+* ```ts
+* import { getDBInfo } from './impl/getDBInfo.mts';
+*
+* const config = { couch: 'http://localhost:5984/my-database' };
+*
+* getDBInfo(config)
+*   .then(info => {
+*     console.log('Database Info:', info);
+*   })
+*   .catch(err => {
+*     console.error('Error fetching database info:', err);
+*   });
+* ```
+*/
+const getDBInfo = async (configInput) => {
+	const config = CouchConfig.parse(configInput);
+	const logger = createLogger(config);
+	const url = `${config.couch}`;
+	let resp;
+	try {
+		resp = await needle("get", url, mergeNeedleOpts(config, {
+			json: true,
+			headers: { "Content-Type": "application/json" }
+		}));
+	} catch (err) {
+		logger.error("Error during get operation:", err);
+		RetryableError.handleNetworkError(err);
+	}
+	if (!resp) {
+		logger.error("No response received from get request");
+		throw new RetryableError("no response", 503);
+	}
+	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);
+};
+
+//#endregion
+//#region schema/sugar/lock.mts
+const LockDoc = CouchDoc.extend({
+	type: z$1.literal("lock"),
+	locks: z$1.string().describe("the document ID being locked"),
+	lockedAt: z$1.string().describe("ISO timestamp when lock was created"),
+	lockedBy: z$1.string().describe("username of who created the lock")
+});
+const LockOptions = z$1.object({
+	enableLocking: z$1.boolean().prefault(true).describe("whether locking is enabled"),
+	username: z$1.string().describe("username to attribute locks to")
+});
+
+//#endregion
+//#region impl/sugar/lock.mts
+/**
+* Create a lock document for the specified document ID.
+* Returns true if the lock was created, false if locking is disabled or a conflict occurred.
+*
+* @param configInput CouchDB configuration
+* @param docId The document ID to lock
+* @param lockOptions Locking options
+*
+* @return True if the lock was created, false otherwise
+*/
+async function createLock(configInput, docId, lockOptions) {
+	const config = CouchConfig.parse(configInput);
+	const options = LockOptions.parse(lockOptions);
+	const logger = createLogger(config);
+	if (!options.enableLocking) {
+		logger.debug("Locking disabled, returning true without creating lock");
+		return true;
+	}
+	const lock = {
+		_id: `lock-${docId}`,
+		type: "lock",
+		locks: docId,
+		lockedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		lockedBy: options.username
+	};
+	try {
+		const result = await put(config, lock);
+		logger.info(`Lock created for ${docId} by ${options.username}`);
+		return result.ok === true;
+	} catch (error) {
+		if (isConflictError(error)) logger.warn(`Lock conflict for ${docId} - already locked`);
+		else logger.error(`Error creating lock for ${docId}:`, error);
+		return false;
+	}
+}
+/**
+* Remove the lock document for the specified document ID if owned by the caller.
+*
+* @param configInput CouchDB configuration
+* @param docId The document ID to unlock
+* @param lockOptions Locking options
+*
+* @return Promise that resolves when the unlock operation is complete
+*/
+async function removeLock(configInput, docId, lockOptions) {
+	const config = CouchConfig.parse(configInput);
+	const options = LockOptions.parse(lockOptions);
+	const logger = createLogger(config);
+	if (!options.enableLocking) {
+		logger.debug("Locking disabled, skipping unlock");
+		return;
+	}
+	if (!docId) {
+		logger.warn("No docId provided for unlock");
+		return;
+	}
+	const existingLock = await get(config, `lock-${docId}`);
+	if (!existingLock) {
+		logger.debug(`No lock found for ${docId}`);
+		return;
+	}
+	if (existingLock.lockedBy !== options.username) {
+		logger.warn(`Cannot remove lock for ${docId} - owned by ${existingLock.lockedBy}`);
+		return;
+	}
+	try {
+		await put(config, {
+			...existingLock,
+			_deleted: true
+		});
+		logger.info(`Lock removed for ${docId}`);
+	} catch (error) {
+		logger.error(`Error removing lock for ${docId}:`, error);
+	}
+}
+
+//#endregion
+//#region schema/sugar/watch.mts
+const WatchOptions = z$1.object({
+	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"),
+	maxDelay: z$1.number().describe("maximum delay between retries in milliseconds")
+}).partial();
+
+//#endregion
+//#region impl/sugar/watch.mts
+/**
+* Watch for changes to specified document IDs in CouchDB.
+* Calls the onChange callback for each change detected.
+* Returns an emitter with methods to listen for events and stop watching.
+*
+* @param configInput CouchDB configuration
+* @param docIds Document ID or array of document IDs to watch
+* @param onChange Callback function called on each change
+* @param optionsInput Watch options
+*
+* @return WatchEmitter with methods to manage the watch
+*/
+function watchDocs(configInput, docIds, onChange, optionsInput = {}) {
+	const config = CouchConfig.parse(configInput);
+	const options = WatchOptions.parse(optionsInput);
+	const logger = createLogger(config);
+	const emitter = new EventEmitter();
+	let lastSeq = null;
+	let stopping = false;
+	let retryCount = 0;
+	let currentRequest = 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");
+	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
+		});
+		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 change = JSON.parse(line);
+				if (!change.id) return null;
+				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) => {
+			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) {
+				logger.info("stopping in progress, ignore stream error");
+				return;
+			}
+			logger.error(`Network error during stream, watching [${_docIds}]:`, err.toString());
+			try {
+				RetryableError.handleNetworkError(err);
+			} catch (filteredError) {
+				if (filteredError instanceof RetryableError) {
+					logger.info(`Retryable error, watching [${_docIds}]:`, filteredError.toString());
+					handleReconnect();
+				} else {
+					logger.error(`Non-retryable error, watching [${_docIds}]`, filteredError?.toString());
+					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"));
+			}
+			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();
+		} catch (err) {
+			logger.error("Error during reconnection:", err);
+			handleReconnect();
+		}
+	};
+	connect();
+	emitter.on("change", onChange);
+	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();
+		}
+	};
+}
+
+//#endregion
+//#region impl/bindConfig.mts
+/**
+* Build a validated binding that exposes CouchDB helpers plus an options() helper for overrides.
+* @param config The CouchDB configuration
+* @returns A bound instance with CouchDB operations and an options() method for overrides
+*/
+const bindConfig = (config) => {
+	const funcs = doBind(CouchConfig.parse(config));
+	const reconfigure = (overrides) => {
+		return bindConfig({
+			...config,
+			...overrides
+		});
+	};
+	return {
+		...funcs,
+		options: reconfigure
+	};
+};
+/**
+* @internal
+*
+* Helper to bind a function to a config, optionally wrapping it with retry logic.
+* Casts to the appropriate bound function type.
+* @param func The function to bind
+* @param config The CouchDB configuration
+* @returns The bound function, possibly wrapped with retry logic
+*/
+function getBoundWithRetry(func, config) {
+	const bound = func.bind(null, config);
+	if (config.bindWithRetry) return withRetry(bound, {
+		maxRetries: config.maxRetries ?? 10,
+		initialDelay: config.initialDelay ?? 1e3,
+		backoffFactor: config.backoffFactor ?? 2
+	});
+	else return bound;
+}
+/**
+* @internal
+*
+* Bind core CouchDB operations to a specific configuration, optionally applying retry wrappers.
+* @param config The CouchDB configuration
+* @returns An object with CouchDB operations bound to the provided configuration
+*/
+function doBind(config) {
+	const retryOptions = {
+		maxRetries: config.maxRetries ?? 10,
+		initialDelay: config.initialDelay ?? 1e3,
+		backoffFactor: config.backoffFactor ?? 2
+	};
+	return {
+		bulkGet: getBoundWithRetry(bulkGet, config),
+		bulkGetDictionary: getBoundWithRetry(bulkGetDictionary, config),
+		get: getBoundWithRetry(get, config),
+		getAtRev: getBoundWithRetry(getAtRev, config),
+		query: getBoundWithRetry(query, config),
+		bulkRemove: config.bindWithRetry ? withRetry(bulkRemove.bind(null, config), retryOptions) : bulkRemove.bind(null, config),
+		bulkRemoveMap: config.bindWithRetry ? withRetry(bulkRemoveMap.bind(null, config), retryOptions) : bulkRemoveMap.bind(null, config),
+		bulkSave: config.bindWithRetry ? withRetry(bulkSave.bind(null, config), retryOptions) : bulkSave.bind(null, config),
+		bulkSaveTransaction: bulkSaveTransaction.bind(null, config),
+		getDBInfo: config.bindWithRetry ? withRetry(getDBInfo.bind(null, config), retryOptions) : getDBInfo.bind(null, config),
+		patch: config.bindWithRetry ? withRetry(patch.bind(null, config), retryOptions) : patch.bind(null, config),
+		patchDangerously: patchDangerously.bind(null, config),
+		put: config.bindWithRetry ? withRetry(put.bind(null, config), retryOptions) : put.bind(null, config),
+		queryStream: config.bindWithRetry ? withRetry(queryStream.bind(null, config), retryOptions) : queryStream.bind(null, config),
+		remove: config.bindWithRetry ? withRetry(remove.bind(null, config), retryOptions) : remove.bind(null, config),
+		createLock: createLock.bind(null, config),
+		removeLock: removeLock.bind(null, config),
+		watchDocs: watchDocs.bind(null, 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 };