hide-a-bed 7.0.0 → 7.1.0

package/dist/esm/index.mjs

@@ -1126,8 +1126,7 @@ const KEYS_TO_QUOTE = [
 	"key",
 	"keys",
 	"startkey",
-	"startkey_docid",
-	"update"
+	"startkey_docid"
 ];
 /**
 * Serialize CouchDB view options into a URL-safe query string, quoting values CouchDB expects as JSON.
@@ -2039,6 +2038,51 @@ const getDBInfo = async (configInput) => {
 	return CouchDBInfo.parse(resp.body);
 };
 
+//#endregion
+//#region impl/headDB.mts
+/**
+* Performs a health check against the target CouchDB database using `HEAD /{db}`.
+*
+* @see {@link https://docs.couchdb.org/en/stable/api/database/common.html#head--db | CouchDB API Documentation}
+*
+* @param configInput - The CouchDB configuration input.
+* @returns A promise that resolves to `true` when the database responds successfully.
+* @throws {RetryableError} `RetryableError` If a retryable error occurs during the request.
+* @throws {OperationError} For other non-retryable response failures.
+*/
+const headDB = async (configInput) => {
+	const config = CouchConfig.parse(configInput);
+	const logger = createLogger(config);
+	const url = createCouchDbUrl(config.couch);
+	let resp;
+	try {
+		resp = await fetchCouchJson({
+			auth: config.auth,
+			method: "HEAD",
+			operation: "headDB",
+			request: config.request,
+			url
+		});
+		if (!isSuccessStatusCode("database", resp.statusCode)) {
+			logger.error(`Non-success status code received: ${resp.statusCode}`);
+			throw createResponseError({
+				body: resp.body,
+				defaultMessage: "Database health check failed",
+				operation: "headDB",
+				statusCode: resp.statusCode
+			});
+		}
+	} catch (err) {
+		logger.error("Error during head operation:", err);
+		RetryableError.handleNetworkError(err, "headDB");
+	}
+	if (!resp) {
+		logger.error("No response received from head request");
+		throw new RetryableError("Database health check failed", 503, { operation: "headDB" });
+	}
+	return true;
+};
+
 //#endregion
 //#region schema/sugar/lock.mts
 const LockDoc = CouchDoc.extend({
@@ -2372,6 +2416,7 @@ function doBind(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),
+		headDB: config.bindWithRetry ? withRetry(headDB.bind(null, config), retryOptions) : headDB.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),
@@ -2384,4 +2429,4 @@ function doBind(config) {
 }
 
 //#endregion
-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 };
+export { ConflictError, HideABedError, NotFoundError, OperationError, QueryBuilder, RetryableError, ValidationError, bindConfig, bulkGet, bulkGetDictionary, bulkRemove, bulkRemoveMap, bulkSave, bulkSaveTransaction, createLock, createQuery, get, getAtRev, getDBInfo, headDB, patch, patchDangerously, put, query, queryStream, remove, removeLock, watchDocs, withRetry };

package/impl/bindConfig.mts

@@ -1,56 +1,58 @@
 // oxlint-disable typescript/no-explicit-any
-import type z from 'zod'
-import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
-import { withRetry } from './retry.mts'
+import type z from "zod";
+import { CouchConfig, type CouchConfigInput } from "../schema/config.mts";
+import { withRetry } from "./retry.mts";
 import {
   type BulkGetBound,
   bulkGet,
   type BulkGetDictionaryBound,
-  bulkGetDictionary
-} from './bulkGet.mts'
-import { type GetBound, type GetAtRevBound, getAtRev, get } from './get.mts'
-import { queryStream } from './stream.mts'
-import { patch, patchDangerously } from './patch.mts'
-import { put } from './put.mts'
-import type { QueryBound } from './query.mts'
-import { query } from './query.mts'
-import { bulkRemove, bulkRemoveMap } from './bulkRemove.mts'
-import { bulkSave, bulkSaveTransaction } from './bulkSave.mts'
-import { getDBInfo } from './getDBInfo.mts'
-import { remove } from './remove.mts'
-import { createLock, removeLock } from './sugar/lock.mts'
-import { watchDocs } from './sugar/watch.mts'
+  bulkGetDictionary,
+} from "./bulkGet.mts";
+import { type GetBound, type GetAtRevBound, getAtRev, get } from "./get.mts";
+import { queryStream } from "./stream.mts";
+import { patch, patchDangerously } from "./patch.mts";
+import { put } from "./put.mts";
+import type { QueryBound } from "./query.mts";
+import { query } from "./query.mts";
+import { bulkRemove, bulkRemoveMap } from "./bulkRemove.mts";
+import { bulkSave, bulkSaveTransaction } from "./bulkSave.mts";
+import { getDBInfo } from "./getDBInfo.mts";
+import { headDB } from "./headDB.mts";
+import { remove } from "./remove.mts";
+import { createLock, removeLock } from "./sugar/lock.mts";
+import { watchDocs } from "./sugar/watch.mts";
 
 type BoundConfigMethod<T> = T extends (...args: infer Args) => infer Result
   ? Args extends [unknown, ...infer Rest]
     ? (...args: Rest) => Result
     : never
-  : never
+  : never;
 
 type BoundMethods = {
-  bulkGet: BulkGetBound
-  bulkGetDictionary: BulkGetDictionaryBound
-  get: GetBound
-  getAtRev: GetAtRevBound
-  query: QueryBound
-  bulkRemove: BoundConfigMethod<typeof bulkRemove>
-  bulkRemoveMap: BoundConfigMethod<typeof bulkRemoveMap>
-  bulkSave: BoundConfigMethod<typeof bulkSave>
-  bulkSaveTransaction: BoundConfigMethod<typeof bulkSaveTransaction>
-  getDBInfo: BoundConfigMethod<typeof getDBInfo>
-  patch: BoundConfigMethod<typeof patch>
-  patchDangerously: BoundConfigMethod<typeof patchDangerously>
-  put: BoundConfigMethod<typeof put>
-  queryStream: BoundConfigMethod<typeof queryStream>
-  remove: BoundConfigMethod<typeof remove>
-  createLock: BoundConfigMethod<typeof createLock>
-  removeLock: BoundConfigMethod<typeof removeLock>
-  watchDocs: BoundConfigMethod<typeof watchDocs>
-}
+  bulkGet: BulkGetBound;
+  bulkGetDictionary: BulkGetDictionaryBound;
+  get: GetBound;
+  getAtRev: GetAtRevBound;
+  query: QueryBound;
+  bulkRemove: BoundConfigMethod<typeof bulkRemove>;
+  bulkRemoveMap: BoundConfigMethod<typeof bulkRemoveMap>;
+  bulkSave: BoundConfigMethod<typeof bulkSave>;
+  bulkSaveTransaction: BoundConfigMethod<typeof bulkSaveTransaction>;
+  getDBInfo: BoundConfigMethod<typeof getDBInfo>;
+  headDB: BoundConfigMethod<typeof headDB>;
+  patch: BoundConfigMethod<typeof patch>;
+  patchDangerously: BoundConfigMethod<typeof patchDangerously>;
+  put: BoundConfigMethod<typeof put>;
+  queryStream: BoundConfigMethod<typeof queryStream>;
+  remove: BoundConfigMethod<typeof remove>;
+  createLock: BoundConfigMethod<typeof createLock>;
+  removeLock: BoundConfigMethod<typeof removeLock>;
+  watchDocs: BoundConfigMethod<typeof watchDocs>;
+};
 
 export type BoundInstance = BoundMethods & {
-  options(overrides: Partial<z.input<typeof CouchConfig>>): BoundInstance
-}
+  options(overrides: Partial<z.input<typeof CouchConfig>>): BoundInstance;
+};
 
 /**
  * Build a validated binding that exposes CouchDB helpers plus an options() helper for overrides.
@@ -58,20 +60,22 @@ export type BoundInstance = BoundMethods & {
  * @returns A bound instance with CouchDB operations and an options() method for overrides
  */
 export const bindConfig = (config: CouchConfigInput): BoundInstance => {
-  const parsedConfig = CouchConfig.parse(config)
+  const parsedConfig = CouchConfig.parse(config);
 
-  const funcs = doBind(parsedConfig)
+  const funcs = doBind(parsedConfig);
 
   // Add the options function that returns a new bound instance
   // this allows the user to override some options
-  const reconfigure: BoundInstance['options'] = (overrides: Partial<CouchConfigInput>) => {
-    const newConfig: z.input<typeof CouchConfig> = { ...config, ...overrides }
-    return bindConfig(newConfig)
-  }
+  const reconfigure: BoundInstance["options"] = (
+    overrides: Partial<CouchConfigInput>,
+  ) => {
+    const newConfig: z.input<typeof CouchConfig> = { ...config, ...overrides };
+    return bindConfig(newConfig);
+  };
 
-  const bound: BoundInstance = { ...funcs, options: reconfigure }
-  return bound
-}
+  const bound: BoundInstance = { ...funcs, options: reconfigure };
+  return bound;
+};
 
 /**
  * @internal
@@ -82,19 +86,21 @@ export const bindConfig = (config: CouchConfigInput): BoundInstance => {
  * @param config The CouchDB configuration
  * @returns The bound function, possibly wrapped with retry logic
  */
-export function getBoundWithRetry<TBound extends (...args: any[]) => Promise<any>>(
+export function getBoundWithRetry<
+  TBound extends (...args: any[]) => Promise<any>,
+>(
   func: (config: CouchConfig, ...args: any[]) => Promise<any>,
-  config: CouchConfig
+  config: CouchConfig,
 ) {
-  const bound = func.bind(null, config)
+  const bound = func.bind(null, config);
   if (config.bindWithRetry) {
     return withRetry(bound, {
       maxRetries: config.maxRetries ?? 10,
       initialDelay: config.initialDelay ?? 1000,
-      backoffFactor: config.backoffFactor ?? 2
-    }) as TBound
+      backoffFactor: config.backoffFactor ?? 2,
+    }) as TBound;
   } else {
-    return bound as TBound
+    return bound as TBound;
   }
 }
 
@@ -110,8 +116,8 @@ function doBind(config: CouchConfig): BoundMethods {
   const retryOptions = {
     maxRetries: config.maxRetries ?? 10,
     initialDelay: config.initialDelay ?? 1000,
-    backoffFactor: config.backoffFactor ?? 2
-  }
+    backoffFactor: config.backoffFactor ?? 2,
+  };
 
   // Create the object without the config property first
   const result: BoundMethods = {
@@ -120,7 +126,10 @@ function doBind(config: CouchConfig): BoundMethods {
      * To preserve the overloads we need dedicated Bound types
      */
     bulkGet: getBoundWithRetry<BulkGetBound>(bulkGet, config),
-    bulkGetDictionary: getBoundWithRetry<BulkGetDictionaryBound>(bulkGetDictionary, config),
+    bulkGetDictionary: getBoundWithRetry<BulkGetDictionaryBound>(
+      bulkGetDictionary,
+      config,
+    ),
     get: getBoundWithRetry<GetBound>(get, config),
     getAtRev: getBoundWithRetry<GetAtRevBound>(getAtRev, config),
     query: getBoundWithRetry<QueryBound>(query, config),
@@ -141,6 +150,9 @@ function doBind(config: CouchConfig): BoundMethods {
     getDBInfo: config.bindWithRetry
       ? withRetry(getDBInfo.bind(null, config), retryOptions)
       : getDBInfo.bind(null, config),
+    headDB: config.bindWithRetry
+      ? withRetry(headDB.bind(null, config), retryOptions)
+      : headDB.bind(null, config),
     patch: config.bindWithRetry
       ? withRetry(patch.bind(null, config), retryOptions)
       : patch.bind(null, config),
@@ -157,8 +169,8 @@ function doBind(config: CouchConfig): BoundMethods {
 
     createLock: createLock.bind(null, config),
     removeLock: removeLock.bind(null, config),
-    watchDocs: watchDocs.bind(null, config)
-  }
+    watchDocs: watchDocs.bind(null, config),
+  };
 
-  return result
+  return result;
 }

package/impl/headDB.mts

@@ -0,0 +1,55 @@
+import { RetryableError, createResponseError } from "./utils/errors.mts";
+import { createLogger } from "./utils/logger.mts";
+import { CouchConfig, type CouchConfigInput } from "../schema/config.mts";
+import { fetchCouchJson } from "./utils/fetch.mts";
+import { isSuccessStatusCode } from "./utils/response.mts";
+import { createCouchDbUrl } from "./utils/url.mts";
+
+/**
+ * Performs a health check against the target CouchDB database using `HEAD /{db}`.
+ *
+ * @see {@link https://docs.couchdb.org/en/stable/api/database/common.html#head--db | CouchDB API Documentation}
+ *
+ * @param configInput - The CouchDB configuration input.
+ * @returns A promise that resolves to `true` when the database responds successfully.
+ * @throws {RetryableError} `RetryableError` If a retryable error occurs during the request.
+ * @throws {OperationError} For other non-retryable response failures.
+ */
+export const headDB = async (configInput: CouchConfigInput): Promise<true> => {
+  const config = CouchConfig.parse(configInput);
+  const logger = createLogger(config);
+  const url = createCouchDbUrl(config.couch);
+
+  let resp;
+  try {
+    resp = await fetchCouchJson({
+      auth: config.auth,
+      method: "HEAD",
+      operation: "headDB",
+      request: config.request,
+      url,
+    });
+
+    if (!isSuccessStatusCode("database", resp.statusCode)) {
+      logger.error(`Non-success status code received: ${resp.statusCode}`);
+      throw createResponseError({
+        body: resp.body,
+        defaultMessage: "Database health check failed",
+        operation: "headDB",
+        statusCode: resp.statusCode,
+      });
+    }
+  } catch (err) {
+    logger.error("Error during head operation:", err);
+    RetryableError.handleNetworkError(err, "headDB");
+  }
+
+  if (!resp) {
+    logger.error("No response received from head request");
+    throw new RetryableError("Database health check failed", 503, {
+      operation: "headDB",
+    });
+  }
+
+  return true;
+};