hide-a-bed 7.0.1 → 7.1.0

package/README.md

@@ -15,6 +15,7 @@
 And some utility APIs
 
 - [`getDBInfo()`](#getdbinfo)
+- [`headDB()`](#headdb)
 - [`createQuery()`](#createquery) 🍭
 - [`withRetry()`](#withretry)
 
@@ -48,25 +49,25 @@ If your CouchDB requires basic auth, pass `auth` on the config:
 
 ```javascript
 const config = {
-  couch: 'https://the.couch.url.com:5984/mydb',
+  couch: "https://the.couch.url.com:5984/mydb",
   auth: {
     username: process.env.COUCHDB_USER,
-    password: process.env.COUCHDB_PASSWORD
-  }
-}
+    password: process.env.COUCHDB_PASSWORD,
+  },
+};
 ```
 
 You can also set default request controls on the config:
 
 ```javascript
 const config = {
-  couch: 'https://the.couch.url.com:5984/mydb',
+  couch: "https://the.couch.url.com:5984/mydb",
   request: {
     timeout: 5000,
     signal: abortController.signal,
-    dispatcher
-  }
-}
+    dispatcher,
+  },
+};
 ```
 
 See [Advanced Config Options](#advanced-config-options) for more advanced settings.
@@ -113,19 +114,19 @@ Get a single document by ID.
 - Throws: `NotFoundError` when the document does not exist and `throwOnGetNotFound` is true
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const doc = await get(config, 'doc-123')
-console.log(doc._id, doc._rev)
+const config = { couch: "http://localhost:5984/mydb" };
+const doc = await get(config, "doc-123");
+console.log(doc._id, doc._rev);
 
-const missing = await get(config, 'notFound')
-console.log(missing) // null
+const missing = await get(config, "notFound");
+console.log(missing); // null
 
 try {
-  await get({ ...config, throwOnGetNotFound: true }, 'notFound')
+  await get({ ...config, throwOnGetNotFound: true }, "notFound");
 } catch (err) {
-  if (err.name === 'NotFoundError') {
-    console.log(err.statusCode) // 404
-    console.log(err.docId) // notFound
+  if (err.name === "NotFoundError") {
+    console.log(err.statusCode); // 404
+    console.log(err.docId); // notFound
   }
 }
 ```
@@ -142,21 +143,21 @@ Save a document.
 - Throws: `ConflictError` when CouchDB returns a 409 for a single-document write
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
+const config = { couch: "http://localhost:5984/mydb" };
 const doc = {
-  _id: 'doc-123',
-  type: 'user',
-  name: 'Alice'
-}
-const result = await put(config, doc)
+  _id: "doc-123",
+  type: "user",
+  name: "Alice",
+};
+const result = await put(config, doc);
 // result: { ok: true, id: 'doc-123', rev: '1-abc123' }
 
 try {
-  await put(config, { _id: 'notThereDoc', _rev: '32-does-not-compute' })
+  await put(config, { _id: "notThereDoc", _rev: "32-does-not-compute" });
 } catch (err) {
-  if (err.name === 'ConflictError') {
-    console.log(err.statusCode) // 409
-    console.log(err.docId) // notThereDoc
+  if (err.name === "ConflictError") {
+    console.log(err.statusCode); // 409
+    console.log(err.docId); // notThereDoc
   }
 }
 ```
@@ -174,15 +175,15 @@ The patch function lets you update specific properties of a document. The \_rev
 
 ```javascript
 const config = {
-  couch: 'http://localhost:5984/mydb',
-  retries: 3
-}
+  couch: "http://localhost:5984/mydb",
+  retries: 3,
+};
 const properties = {
-  _rev: '3-fdskjhfsdkjhfsd',
-  name: 'Alice Smith',
-  updated: true
-}
-const result = await patch(config, 'doc-123', properties)
+  _rev: "3-fdskjhfsdkjhfsd",
+  name: "Alice Smith",
+  updated: true,
+};
+const result = await patch(config, "doc-123", properties);
 // result: { ok: true, id: 'doc-123', rev: '2-xyz789' }
 ```
 
@@ -204,14 +205,14 @@ _Warning_: patchDangerously can clobber data. It will retry even if a conflict h
 
 ```javascript
 const config = {
-  couch: 'http://localhost:5984/mydb',
-  retries: 3
-}
+  couch: "http://localhost:5984/mydb",
+  retries: 3,
+};
 const properties = {
-  name: 'Alice Smith',
-  updated: true
-}
-const result = await patchDangerously(config, 'doc-123', properties)
+  name: "Alice Smith",
+  updated: true,
+};
+const result = await patchDangerously(config, "doc-123", properties);
 // result: { ok: true, id: 'doc-123', rev: '2-xyz789' }
 ```
 
@@ -228,9 +229,9 @@ Return a document at the rev specified.
 _CouchDB_ is not a version control db. This is a special function for unique situations. The \_rev might not be around as couch cleans up old revs.
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const doc = await getAtRev(config, 'doc-123', '2-fsdjfsdakljfsajlksd')
-console.log(doc._id, doc._rev)
+const config = { couch: "http://localhost:5984/mydb" };
+const doc = await getAtRev(config, "doc-123", "2-fsdjfsdakljfsajlksd");
+console.log(doc._id, doc._rev);
 ```
 
 #### createLock
@@ -266,17 +267,17 @@ Remove a lock from a document.
 Only the user who created the lock can remove it.
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
+const config = { couch: "http://localhost:5984/mydb" };
 const options = {
   enableLocking: true,
-  username: 'alice'
-}
+  username: "alice",
+};
 
-const locked = await createLock(config, 'doc-123', options)
+const locked = await createLock(config, "doc-123", options);
 if (locked) {
   // Document is now locked for exclusive access
   // Perform your updates here
-  await removeLock(config, 'doc-123', options)
+  await removeLock(config, "doc-123", options);
 }
 // Lock is now removed if it existed and was owned by 'alice'
 ```
@@ -294,12 +295,12 @@ Save multiple documents in one request.
 - Returns: Promise resolving to array of results with `ok`, `id`, `rev` for each doc
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
+const config = { couch: "http://localhost:5984/mydb" };
 const docs = [
-  { _id: 'doc1', type: 'user', name: 'Alice' },
-  { _id: 'doc2', type: 'user', name: 'Bob' }
-]
-const results = await bulkSave(config, docs)
+  { _id: "doc1", type: "user", name: "Alice" },
+  { _id: "doc2", type: "user", name: "Bob" },
+];
+const results = await bulkSave(config, docs);
 // [
 //   { ok: true, id: 'doc1', rev: '1-abc123' },
 //   { ok: true, id: 'doc2', rev: '1-def456' }
@@ -321,17 +322,17 @@ Get multiple documents by ID.
 Warning: documents that are not found will still have a row in the results. The doc property will be null, and the error property will be set.
 
 ```javascript
-import z from 'zod'
+import z from "zod";
 
-const config = { couch: 'http://localhost:5984/mydb' }
-const ids = ['doc1', 'doc2', 'doesNotExist']
+const config = { couch: "http://localhost:5984/mydb" };
+const ids = ["doc1", "doc2", "doesNotExist"];
 const docs = await bulkGet(config, ids, {
   docSchema: z.looseObject({
     _id: z.string(),
     type: z.string(),
-    name: z.string()
-  })
-})
+    name: z.string(),
+  }),
+});
 // rows: [
 //   { id: 'doc1', doc: { _id: 'doc1', type: 'user', name: 'Alice' } },
 //   { id: 'doc2', doc: { _id: 'doc2', type: 'user', name: 'Bob' } },
@@ -351,9 +352,9 @@ Delete multiple documents in one request.
 - Throws: `RetryableError` or `OperationError` only for request-level failures. Missing documents remain item-level outcomes.
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const ids = ['doc1', 'doc2']
-const results = await bulkRemove(config, ids)
+const config = { couch: "http://localhost:5984/mydb" };
+const ids = ["doc1", "doc2"];
+const results = await bulkRemove(config, ids);
 // results: [
 //   { ok: true, id: 'doc1', rev: '2-ghi789' },
 //   { ok: true, id: 'doc2', rev: '2-jkl012' }
@@ -375,10 +376,10 @@ Allows more efficient deletion of document by providing only id and rev. This is
 - Throws: `NotFoundError` when the document does not exist
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const id = 'doc1'
-const rev = '2-ghi789'
-const result = await remove(config, id, rev)
+const config = { couch: "http://localhost:5984/mydb" };
+const id = "doc1";
+const rev = "2-ghi789";
+const result = await remove(config, id, rev);
 // result:
 //   { ok: true, id: 'doc1', rev: '2-ghi789' }
 ```
@@ -395,9 +396,9 @@ Delete multiple documents in one request. Same inputs and outputs as [bulkRemove
 - Throws: `RetryableError` or `OperationError` only for request-level failures while deleting an item. Missing or otherwise unremovable items are skipped.
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const ids = ['doc1', 'doc2']
-const results = await bulkRemoveMap(config, ids)
+const config = { couch: "http://localhost:5984/mydb" };
+const ids = ["doc1", "doc2"];
+const results = await bulkRemoveMap(config, ids);
 // results: [
 //   { ok: true, id: 'doc1', rev: '2-ghi789' },
 //   { ok: true, id: 'doc2', rev: '2-jkl012' }
@@ -434,16 +435,16 @@ _notFound_ looks like
 ```
 
 ```javascript
-import z from 'zod'
+import z from "zod";
 
-const config = { couch: 'http://localhost:5984/mydb' }
-const ids = ['doc1', 'doc2', 'doesNotExist']
+const config = { couch: "http://localhost:5984/mydb" };
+const ids = ["doc1", "doc2", "doesNotExist"];
 const results = await bulkGetDictionary(config, ids, {
   docSchema: z.looseObject({
     _id: z.string(),
-    data: z.record(z.any())
-  })
-})
+    data: z.record(z.any()),
+  }),
+});
 // results: {
 //   found: {
 //     doc1: { _id: 'doc2', _rev: '1-221', data: {} },
@@ -478,28 +479,28 @@ Exceptions to handle:
 - `TransactionRollbackError`: Thrown if the rollback operation fails after a transaction failure.
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const transactionId = 'txn-123'
+const config = { couch: "http://localhost:5984/mydb" };
+const transactionId = "txn-123";
 const docs = [
-  { _id: 'doc1', type: 'user', name: 'Alice', _rev: '1-abc123' },
-  { _id: 'doc2', type: 'user', name: 'Bob', _rev: '1-def456' }
-]
+  { _id: "doc1", type: "user", name: "Alice", _rev: "1-abc123" },
+  { _id: "doc2", type: "user", name: "Bob", _rev: "1-def456" },
+];
 
 try {
-  const results = await bulkSaveTransaction(config, transactionId, docs)
-  console.log('Transaction successful:', results)
+  const results = await bulkSaveTransaction(config, transactionId, docs);
+  console.log("Transaction successful:", results);
 } catch (error) {
   if (error instanceof TransactionSetupError) {
     // the transaction could not start - usually an existing transaction with the same id
-    console.error('Transaction setup failed:', error)
+    console.error("Transaction setup failed:", error);
   } else if (error instanceof TransactionVersionConflictError) {
     // one or more of the versions of the docs provided dont match with what is currently in the db
-    console.error('Version conflict error:', error)
+    console.error("Version conflict error:", error);
   } else if (error instanceof TransactionRollbackError) {
     // the transaction was rolled back - so the 'or none' condition occured
-    console.error('Rollback error:', error)
+    console.error("Rollback error:", error);
   } else {
-    console.error('Unexpected error:', error)
+    console.error("Unexpected error:", error);
   }
 }
 ```
@@ -517,6 +518,19 @@ const result = await getDBInfo({
 // result: { db_name: 'test', doc_count: 3232 }
 ```
 
+#### headDB()
+
+Run a lightweight database health check using CouchDB's `HEAD /{db}` route.
+
+```javascript
+const config = { couch: "http://localhost:5984/mydb" };
+const healthy = await headDB({
+  ...config,
+  request: { timeout: 2000 },
+});
+// healthy: true
+```
+
 ### View Queries
 
 #### query
@@ -541,15 +555,15 @@ Query a view with options.
 - Returns: Promise resolving to response with `rows` array
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
-const view = '_design/users/_view/by_name'
+const config = { couch: "http://localhost:5984/mydb" };
+const view = "_design/users/_view/by_name";
 const options = {
-  startkey: 'A',
-  endkey: 'B',
+  startkey: "A",
+  endkey: "B",
   include_docs: true,
-  limit: 10
-}
-const result = await query(config, view, options)
+  limit: 10,
+};
+const result = await query(config, view, options);
 // result: {
 //   rows: [
 //     {
@@ -588,9 +602,14 @@ Create a query builder to help construct view queries with a fluent interface. N
   - `build()`: Return the constructed query options object
 
 ```javascript
-const options = createQuery().startkey('A').endkey('B').include_docs(true).limit(10).build()
+const options = createQuery()
+  .startkey("A")
+  .endkey("B")
+  .include_docs(true)
+  .limit(10)
+  .build();
 
-const result = await query(config, view, options)
+const result = await query(config, view, options);
 ```
 
 Again, use js types for array keys
@@ -656,22 +675,22 @@ npm install hide-a-bed-changes
 Usage mirrors the original API:
 
 ```javascript
-import { changes } from 'hide-a-bed-changes'
+import { changes } from "hide-a-bed-changes";
 
-const config = { couch: 'http://localhost:5984/mydb' }
+const config = { couch: "http://localhost:5984/mydb" };
 
 const feed = await changes(
   config,
-  change => {
-    console.log('Document changed:', change.id)
+  (change) => {
+    console.log("Document changed:", change.id);
   },
-  { since: 'now', include_docs: true }
-)
+  { since: "now", include_docs: true },
+);
 
-feed.on('error', console.error)
+feed.on("error", console.error);
 
 // later
-feed.stop()
+feed.stop();
 ```
 
 `hide-a-bed-changes` reuses the same config structure and resolves `since: 'now'` to the current `update_seq` before starting the feed.
@@ -700,38 +719,38 @@ Returns an EventEmitter that emits:
 - 'end' events with last sequence number.
 
 ```javascript
-const config = { couch: 'http://localhost:5984/mydb' }
+const config = { couch: "http://localhost:5984/mydb" };
 
 // Watch a single document
-const feed = await watchDocs(config, 'doc123', change => {
-  console.log('Document changed:', change.id)
-  console.log('New revision:', change.changes[0].rev)
-})
+const feed = await watchDocs(config, "doc123", (change) => {
+  console.log("Document changed:", change.id);
+  console.log("New revision:", change.changes[0].rev);
+});
 
 // Watch multiple documents with full doc content
 const feed = await watchDocs(
   config,
-  ['doc1', 'doc2', 'doc3'],
-  change => {
+  ["doc1", "doc2", "doc3"],
+  (change) => {
     if (change.doc) {
-      console.log('Updated document:', change.doc)
+      console.log("Updated document:", change.doc);
     }
   },
-  { include_docs: true }
-)
+  { include_docs: true },
+);
 
 // Handle errors
-feed.on('error', error => {
-  console.error('Watch error:', error)
-})
+feed.on("error", (error) => {
+  console.error("Watch error:", error);
+});
 
 // Handle end of feed
-feed.on('end', ({ lastSeq }) => {
-  console.log('Feed ended at sequence:', lastSeq)
-})
+feed.on("end", ({ lastSeq }) => {
+  console.log("Feed ended at sequence:", lastSeq);
+});
 
 // Stop watching
-feed.stop()
+feed.stop();
 ```
 
 The watchDocs feed is useful for:
@@ -761,13 +780,13 @@ Example configuration with all options:
 
 ```javascript
 const config = {
-  couch: 'http://localhost:5984/mydb',
+  couch: "http://localhost:5984/mydb",
   auth: {
     username: process.env.COUCHDB_USER,
-    password: process.env.COUCHDB_PASSWORD
+    password: process.env.COUCHDB_PASSWORD,
   },
   request: {
-    timeout: 5000
+    timeout: 5000,
   },
   throwOnGetNotFound: true,
   bindWithRetry: true,
@@ -775,8 +794,8 @@ const config = {
   initialDelay: 2000,
   backoffFactor: 1.5,
   useConsoleLogger: true,
-  logger: (level, ...args) => console.log(level, ...args)
-}
+  logger: (level, ...args) => console.log(level, ...args),
+};
 ```
 
 `bindConfig()` and `withRetry()` now perform a single built-in retry for transient `401` and `403` responses before surfacing the error.
@@ -786,12 +805,15 @@ const config = {
 `withRetry(fn, options)` wraps an async function and retries based on the built-in retry rules.
 
 ```javascript
-import { withRetry, get } from 'hide-a-bed'
+import { withRetry, get } from "hide-a-bed";
 
-const getWithCustomRetry = withRetry(id => get({ couch: 'http://localhost:5984/mydb' }, id), {
-  maxRetries: 2,
-  initialDelay: 250
-})
+const getWithCustomRetry = withRetry(
+  (id) => get({ couch: "http://localhost:5984/mydb" }, id),
+  {
+    maxRetries: 2,
+    initialDelay: 250,
+  },
+);
 ```
 
 ### Migration Note
@@ -809,26 +831,26 @@ The library supports flexible logging options that can be configured through the
 ```javascript
 // Enable console logging (error, warn, info, debug)
 const config = {
-  couch: 'http://localhost:5984/mydb',
-  useConsoleLogger: true
-}
+  couch: "http://localhost:5984/mydb",
+  useConsoleLogger: true,
+};
 
 // Use a custom logger object (winston-style)
 const config = {
-  couch: 'http://localhost:5984/mydb',
+  couch: "http://localhost:5984/mydb",
   logger: {
-    error: msg => console.error(msg),
-    warn: msg => console.warn(msg),
-    info: msg => console.info(msg),
-    debug: msg => console.debug(msg)
-  }
-}
+    error: (msg) => console.error(msg),
+    warn: (msg) => console.warn(msg),
+    info: (msg) => console.info(msg),
+    debug: (msg) => console.debug(msg),
+  },
+};
 
 // Use a simple function logger
 const config = {
-  couch: 'http://localhost:5984/mydb',
-  logger: (level, ...args) => console.log(level, ...args)
-}
+  couch: "http://localhost:5984/mydb",
+  logger: (level, ...args) => console.log(level, ...args),
+};
 ```
 
 The logger will track operations including:

package/dist/cjs/index.cjs

@@ -2070,6 +2070,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({
@@ -2403,6 +2448,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),
@@ -2434,6 +2480,7 @@ exports.createQuery = createQuery;
 exports.get = get;
 exports.getAtRev = getAtRev;
 exports.getDBInfo = getDBInfo;
+exports.headDB = headDB;
 exports.patch = patch;
 exports.patchDangerously = patchDangerously;
 exports.put = put;