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

package/impl/patch.mts

@@ -4,6 +4,7 @@ import { createLogger } from './utils/logger.mts'
 import { setTimeout } from 'node:timers/promises'
 import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
 import { z } from 'zod'
+import { ConflictError, HideABedError, OperationError, RetryableError } from './utils/errors.mts'
 
 const PatchProperties = z
   .looseObject({
@@ -20,7 +21,10 @@ const PatchProperties = z
  * @param _properties - Properties to merge into the document (must include _rev)
  * @returns The result of the put operation
  *
- * @throws Error if the _rev does not match or other errors occur
+ * @throws {ConflictError} When the supplied `_rev` does not match the current document revision.
+ * @throws {NotFoundError} When the document does not exist.
+ * @throws {RetryableError} When a retryable transport or HTTP failure occurs while reading or saving.
+ * @throws {OperationError} When a non-retryable operational failure occurs.
  */
 export const patch = async (
   configInput: CouchConfigInput,
@@ -33,13 +37,15 @@ export const patch = async (
 
   logger.info(`Starting patch operation for document ${id}`)
   logger.debug('Patch properties:', properties)
-  const doc = await get(config, id)
-  if (doc?._rev !== properties._rev) {
-    return {
-      statusCode: 409,
-      ok: false,
-      error: 'conflict'
-    }
+  const doc = await get({ ...config, throwOnGetNotFound: true }, id)
+  if (!doc) {
+    throw new OperationError('Patch failed', {
+      docId: id,
+      operation: 'patch'
+    })
+  }
+  if (doc._rev !== properties._rev) {
+    throw new ConflictError(id, { operation: 'patch' })
   }
 
   const updatedDoc = { ...doc, ...properties }
@@ -60,7 +66,9 @@ export const patch = async (
  * @param properties - Properties to merge into the document
  * @returns The result of the put operation or an error if max retries are exceeded
  *
- * @throws Error if max retries are exceeded or other errors occur
+ * @throws {NotFoundError} When the document does not exist.
+ * @throws {RetryableError} When a retryable transport or HTTP failure occurs before retries are exhausted.
+ * @throws {OperationError} When retries are exhausted or a non-retryable operational failure occurs.
  */
 export const patchDangerously = async (
   configInput: CouchConfigInput,
@@ -75,60 +83,56 @@ export const patchDangerously = async (
 
   logger.info(`Starting patch operation for document ${id}`)
   logger.debug('Patch properties:', properties)
+  let lastError: unknown
 
   while (attempts <= maxRetries) {
     logger.debug(`Attempt ${attempts + 1} of ${maxRetries + 1}`)
     try {
-      const doc = await get(config, id)
+      const doc = await get({ ...config, throwOnGetNotFound: true }, id)
       if (!doc) {
-        logger.warn(`Document ${id} not found`)
-        return { ok: false, statusCode: 404, error: 'not_found' }
+        throw new OperationError('Patch failed', {
+          docId: id,
+          operation: 'patchDangerously'
+        })
       }
-
       const updatedDoc = { ...doc, ...properties }
       logger.debug('Merged document:', updatedDoc)
 
       const result = await put(config, updatedDoc)
-
-      // Check if the response indicates a conflict
-      if (result.ok) {
-        logger.info(`Successfully patched document ${id}, rev: ${result.rev}`)
-        return result
-      }
-
-      // If not ok, treat as conflict and retry
-      attempts++
-      if (attempts > maxRetries) {
-        logger.error(`Failed to patch ${id} after ${maxRetries} attempts`)
-        throw new Error(`Failed to patch after ${maxRetries} attempts`)
+      logger.info(`Successfully patched document ${id}, rev: ${result.rev}`)
+      return result
+    } catch (err) {
+      if (!(err instanceof Error)) {
+        throw err
       }
 
-      logger.warn(`Conflict detected for ${id}, retrying (attempt ${attempts})`)
-      await setTimeout(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' }
+      if (!(err instanceof ConflictError) && !(err instanceof RetryableError)) {
+        throw err
       }
 
-      // Handle other errors (network, etc)
+      lastError = err
       attempts++
       if (attempts > maxRetries) {
-        const error = `Failed to patch after ${maxRetries} attempts: ${err}`
-        logger.error(error)
-        return { ok: false, statusCode: 500, error }
+        logger.error(`Failed to patch ${id} after ${maxRetries} attempts`, err)
+        throw new OperationError('Patch failed', {
+          cause: err,
+          couchError: err instanceof HideABedError ? err.couchError : undefined,
+          docId: id,
+          operation: 'patchDangerously',
+          statusCode: err instanceof HideABedError ? err.statusCode : undefined
+        })
       }
 
       logger.warn(`Error during patch attempt ${attempts}: ${err}`)
       await setTimeout(delay)
+      delay *= config.backoffFactor || 2
       logger.debug(`Retrying after ${delay}ms`)
     }
   }
+
+  throw new OperationError('Patch failed', {
+    cause: lastError,
+    docId: id,
+    operation: 'patchDangerously'
+  })
 }

package/impl/put.mts

@@ -1,10 +1,18 @@
-import needle from 'needle'
 import { createLogger } from './utils/logger.mts'
-import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
-import { RetryableError } from './utils/errors.mts'
+import { ConflictError, RetryableError, createResponseError } from './utils/errors.mts'
 import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
 import { CouchPutResponse, type CouchDoc } from '../schema/couch/couch.output.schema.ts'
 import { z } from 'zod'
+import { fetchCouchJson } from './utils/fetch.mts'
+import { isRecord, isSuccessStatusCode } from './utils/response.mts'
+import { createCouchDocUrl } from './utils/url.mts'
+
+type CouchMutationBody = {
+  error?: string
+  ok?: boolean
+  reason?: string
+  statusCode?: number
+} & Record<string, unknown>
 
 export const put = async (
   configInput: CouchConfigInput,
@@ -12,43 +20,53 @@ export const put = async (
 ): Promise<z.infer<typeof CouchPutResponse>> => {
   const config = CouchConfig.parse(configInput)
   const logger = createLogger(config)
-  const url = `${config.couch}/${doc._id}`
+  const url = createCouchDocUrl(doc._id, config.couch)
   const body = doc
-  const opts = {
-    json: true,
-    headers: {
-      'Content-Type': 'application/json'
-    }
-  }
-  const mergedOpts = mergeNeedleOpts(config, opts)
 
   logger.info(`Putting document with id: ${doc._id}`)
   let resp
   try {
-    resp = await needle('put', url, body, mergedOpts)
+    resp = await fetchCouchJson({
+      auth: config.auth,
+      method: 'PUT',
+      operation: 'put',
+      request: config.request,
+      url,
+      body
+    })
   } catch (err) {
     logger.error('Error during put operation:', err)
-    RetryableError.handleNetworkError(err)
+    RetryableError.handleNetworkError(err, 'put')
   }
 
   if (!resp) {
     logger.error('No response received from put request')
-    throw new RetryableError('no response', 503)
+    throw new RetryableError('Put failed', 503, { operation: 'put' })
   }
 
-  const result = resp?.body || {}
+  const result: CouchMutationBody = {
+    ...(isRecord(resp.body) ? resp.body : {})
+  }
   result.statusCode = resp.statusCode
 
   if (resp.statusCode === 409) {
     logger.warn(`Conflict detected for document: ${doc._id}`)
-    result.ok = false
-    result.error = 'conflict'
-    return CouchPutResponse.parse(result)
+    throw new ConflictError(doc._id, {
+      couchError: typeof result.error === 'string' ? result.error : undefined,
+      operation: 'put',
+      statusCode: resp.statusCode
+    })
   }
 
-  if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
-    logger.warn(`Retryable status code received: ${resp.statusCode}`)
-    throw new RetryableError(result.reason || 'retryable error', resp.statusCode)
+  if (!isSuccessStatusCode('documentWrite', resp.statusCode) || !result.ok) {
+    logger.error(`Unexpected status code: ${resp.statusCode}`)
+    throw createResponseError({
+      body: resp.body,
+      defaultMessage: 'Put failed',
+      docId: doc._id,
+      operation: 'put',
+      statusCode: resp.statusCode
+    })
   }
 
   logger.info(`Successfully saved document: ${doc._id}`)

package/impl/query.mts

@@ -1,15 +1,57 @@
-import needle, { type BodyData, type NeedleHttpVerbs } from 'needle'
 import { createLogger } from './utils/logger.mts'
 
 import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
 import { z, ZodAny, ZodNever } from 'zod'
 import { queryString } from './utils/queryString.mts'
-import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
-import { RetryableError } from './utils/errors.mts'
+import { RetryableError, createResponseError } from './utils/errors.mts'
 import { ViewOptions, type ViewString } from '../schema/couch/couch.input.schema.ts'
 import type { CouchDoc, ViewQueryResponseValidated } from '../schema/couch/couch.output.schema.ts'
 import type { StandardSchemaV1 } from '../types/standard-schema.ts'
 import { parseRows, type OnInvalidDocAction } from './utils/parseRows.mts'
+import { fetchCouchJson } from './utils/fetch.mts'
+import { isSuccessStatusCode } from './utils/response.mts'
+import { createCouchPathUrl } from './utils/url.mts'
+
+type QueryBody = {
+  error?: string
+  reason?: string
+  rows?: unknown[]
+} & Record<string, unknown>
+
+const ValidSchema = z.custom(
+  value => {
+    return value !== null && typeof value === 'object' && '~standard' in value
+  },
+  {
+    message: 'schema must be a valid StandardSchemaV1 schema'
+  }
+)
+
+const QueryValidationSchema = z
+  .object({
+    docSchema: ValidSchema.optional(),
+    keySchema: ValidSchema.optional(),
+    onInvalidDoc: z.enum(['skip', 'throw']).optional(),
+    valueSchema: ValidSchema.optional()
+  })
+  .optional()
+
+const QueryOptionsSchema = ViewOptions.extend({
+  validate: QueryValidationSchema
+}).strict()
+
+type QueryRequestOptions<
+  DocSchema extends StandardSchemaV1,
+  KeySchema extends StandardSchemaV1,
+  ValueSchema extends StandardSchemaV1
+> = ViewOptions & {
+  validate?: {
+    onInvalidDoc?: OnInvalidDocAction
+    docSchema?: DocSchema
+    keySchema?: KeySchema
+    valueSchema?: ValueSchema
+  }
+}
 
 export async function query<
   DocSchema extends StandardSchemaV1 = typeof CouchDoc,
@@ -18,14 +60,8 @@ export async function query<
 >(
   config: CouchConfigInput,
   view: ViewString,
-  options: ViewOptions & {
+  options: QueryRequestOptions<DocSchema, KeySchema, ValueSchema> & {
     include_docs: true
-    validate?: {
-      onInvalidDoc?: OnInvalidDocAction
-      docSchema?: DocSchema
-      keySchema?: KeySchema
-      valueSchema?: ValueSchema
-    }
   }
 ): Promise<ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>>
 
@@ -36,14 +72,8 @@ export async function query<
 >(
   config: CouchConfigInput,
   view: ViewString,
-  options: ViewOptions & {
+  options: QueryRequestOptions<DocSchema, KeySchema, ValueSchema> & {
     include_docs?: false | undefined
-    validate?: {
-      onInvalidDoc?: OnInvalidDocAction
-      docSchema?: DocSchema
-      keySchema?: KeySchema
-      valueSchema?: ValueSchema
-    }
   }
 ): Promise<ViewQueryResponseValidated<ZodNever, KeySchema, ValueSchema>>
 
@@ -72,8 +102,8 @@ export async function query(
  * @returns The parsed view response with rows validated against the supplied schemas.
  *
  * @throws {RetryableError} When a retryable HTTP status code is encountered or no response is received.
- * @throws {Error<Array<StandardSchemaV1.Issue>>} When the configuration or validation schemas fail to parse.
- * @throws {Error} When CouchDB returns a non-retryable error payload.
+ * @throws {ValidationError} When row, key, value, or included document validation fails.
+ * @throws {OperationError} When CouchDB returns a non-retryable response or malformed row payload.
  */
 export async function query<
   DocSchema extends StandardSchemaV1,
@@ -82,19 +112,13 @@ export async function query<
 >(
   _config: CouchConfigInput,
   view: ViewString,
-  options: ViewOptions & {
-    validate?: {
-      onInvalidDoc?: OnInvalidDocAction
-      docSchema?: DocSchema
-      keySchema?: KeySchema
-      valueSchema?: ValueSchema
-    }
-  } = {}
+  options: QueryRequestOptions<DocSchema, KeySchema, ValueSchema> = {}
 ): Promise<ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>> {
   const configParseResult = CouchConfig.safeParse(_config)
+  const parsedOptions = QueryOptionsSchema.parse(options || {})
   const logger = createLogger(_config)
   logger.info(`Starting view query: ${view}`)
-  logger.debug('Query options:', ViewOptions.parse(options || {}))
+  logger.debug('Query options:', parsedOptions)
   if (!configParseResult.success) {
     logger.error(`Invalid configuration provided: ${z.prettifyError(configParseResult.error)}`)
     throw configParseResult.error
@@ -102,86 +126,94 @@ export async function query<
 
   const config = configParseResult.data
 
-  let qs = queryString(options)
-  let method: NeedleHttpVerbs = 'get'
-  let payload: BodyData = null
-
-  const opts = {
-    json: true,
-    headers: {
-      'Content-Type': 'application/json'
-    }
-  }
-
-  const mergedOpts = mergeNeedleOpts(config, opts)
+  let qs = queryString(parsedOptions)
+  let method: 'GET' | 'POST' = 'GET'
+  let payload: Record<string, unknown> | null = null
 
   // If keys are supplied, issue a POST to circumvent GET query string limits
   // see http://wiki.apache.org/couchdb/HTTP_view_API#Querying_Options
-  if (typeof options.keys !== 'undefined') {
+  if (typeof parsedOptions.keys !== 'undefined') {
     const MAX_URL_LENGTH = 2000
     // according to http://stackoverflow.com/a/417184/680742,
     // the de facto URL length limit is 2000 characters
 
-    const _options = structuredClone(options)
-    delete _options.keys
-    qs = queryString(_options)
+    const { keys, validate, ...queryableOptions } = parsedOptions
+    qs = queryString(queryableOptions)
 
-    const keysAsString = `keys=${JSON.stringify(options.keys)}`
+    const keysAsString = `keys=${JSON.stringify(keys)}`
 
     if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) {
       // If the keys are short enough, do a GET. we do this to work around
       // Safari not understanding 304s on POSTs (see pouchdb/pouchdb#1239)
-      method = 'get'
+      method = 'GET'
       if (qs.length > 0) qs += '&'
       else qs = ''
       qs += keysAsString
     } else {
-      method = 'post'
-      payload = { keys: options.keys }
+      method = 'POST'
+      payload = { keys: parsedOptions.keys }
     }
   }
 
   logger.debug('Generated query string:', qs)
-  const url = `${config.couch}/${view}?${qs}`
+  const url = createCouchPathUrl(view, config.couch)
+  if (qs) url.search = qs
   let results
 
   try {
     logger.debug(`Sending ${method} request to: ${url}`)
-    results =
-      method === 'get'
-        ? await needle('get', url, mergedOpts)
-        : await needle('post', url, payload, mergedOpts)
+    results = await fetchCouchJson<QueryBody>({
+      auth: config.auth,
+      method,
+      operation: 'query',
+      request: config.request,
+      url,
+      body: method === 'POST' ? payload : undefined
+    })
   } catch (err) {
     logger.error('Network error during query:', err)
-    RetryableError.handleNetworkError(err)
+    RetryableError.handleNetworkError(err, 'query')
   }
 
   if (!results) {
     logger.error('No response received from query request')
-    throw new RetryableError('no response', 503)
+    throw new RetryableError('Query failed', 503, { operation: 'query' })
   }
 
   const body = results.body
 
-  if (RetryableError.isRetryableStatusCode(results.statusCode)) {
-    logger.warn(`Retryable status code received: ${results.statusCode}`)
-    throw new RetryableError(body.error || 'retryable error during query', results.statusCode)
-  }
+  if (!isSuccessStatusCode('viewQuery', results.statusCode) || body.error) {
+    if (body.error) {
+      logger.error(`Query error: ${JSON.stringify(body)}`)
+    } else {
+      logger.error(`Unexpected status code: ${results.statusCode}`)
+    }
 
-  if (body.error) {
-    logger.error(`Query error: ${JSON.stringify(body)}`)
-    throw new Error(`CouchDB query error: ${body.error} - ${body.reason || ''}`)
+    throw createResponseError({
+      body,
+      defaultMessage: 'Query failed',
+      operation: 'query',
+      statusCode: results.statusCode
+    })
   }
 
   // If validation schemas are provided, validate each row accordingly
-  if (options.validate && body.rows) {
-    body.rows = await parseRows<DocSchema, KeySchema, ValueSchema>(body.rows, options.validate)
-  }
+  const rows: ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>['rows'] =
+    options.validate && body.rows
+      ? await parseRows<DocSchema, KeySchema, ValueSchema>(body.rows, {
+          ...options.validate,
+          defaultMessage: 'Query failed',
+          operation: 'query'
+        })
+      : ((body.rows ?? []) as ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>['rows'])
 
   logger.info(`Successfully executed view query: ${view}`)
-  logger.debug('Query response:', body)
+  logger.debug('Query response:', { ...body, rows })
 
-  return body
+  return {
+    ...body,
+    rows
+  }
 }
 
 export type QueryBound = {
@@ -191,14 +223,8 @@ export type QueryBound = {
     ValueSchema extends StandardSchemaV1 = ZodAny
   >(
     view: ViewString,
-    options: ViewOptions & {
+    options: QueryRequestOptions<DocSchema, KeySchema, ValueSchema> & {
       include_docs: true
-      validate?: {
-        onInvalidDoc?: OnInvalidDocAction
-        docSchema?: DocSchema
-        keySchema?: KeySchema
-        valueSchema?: ValueSchema
-      }
     }
   ): Promise<ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>>
   <
@@ -207,14 +233,8 @@ export type QueryBound = {
     ValueSchema extends StandardSchemaV1 = ZodAny
   >(
     view: ViewString,
-    options: ViewOptions & {
+    options: QueryRequestOptions<DocSchema, KeySchema, ValueSchema> & {
       include_docs?: false | undefined
-      validate?: {
-        onInvalidDoc?: OnInvalidDocAction
-        docSchema?: DocSchema
-        keySchema?: KeySchema
-        valueSchema?: ValueSchema
-      }
     }
   ): Promise<ViewQueryResponseValidated<ZodNever, KeySchema, ValueSchema>>
   (

package/impl/remove.mts

@@ -1,63 +1,63 @@
-import needle from 'needle'
 import { createLogger } from './utils/logger.mts'
-import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
-import { RetryableError } from './utils/errors.mts'
+import { NotFoundError, RetryableError, createResponseError } from './utils/errors.mts'
 import { CouchPutResponse } from '../schema/couch/couch.output.schema.ts'
 import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
+import { fetchCouchJson } from './utils/fetch.mts'
+import { isRecord, isSuccessStatusCode } from './utils/response.mts'
+import { createCouchDocUrl } from './utils/url.mts'
+
+type CouchMutationBody = {
+  error?: string
+  ok?: boolean
+  reason?: string
+  statusCode?: number
+} & Record<string, unknown>
 
 export const remove = async (configInput: CouchConfigInput, id: string, rev: string) => {
   const config = CouchConfig.parse(configInput)
   const logger = createLogger(config)
-  const url = `${config.couch}/${id}?rev=${rev}`
-  const opts = {
-    json: true,
-    headers: {
-      'Content-Type': 'application/json'
-    }
-  }
-  const mergedOpts = mergeNeedleOpts(config, opts)
+  const url = createCouchDocUrl(id, config.couch)
+  url.searchParams.set('rev', rev)
 
   logger.info(`Deleting document with id: ${id}`)
   let resp
   try {
-    resp = await needle('delete', url, null, mergedOpts)
+    resp = await fetchCouchJson({
+      auth: config.auth,
+      method: 'DELETE',
+      operation: 'remove',
+      request: config.request,
+      url
+    })
   } catch (err) {
     logger.error('Error during delete operation:', err)
-    RetryableError.handleNetworkError(err)
+    RetryableError.handleNetworkError(err, 'remove')
   }
 
   if (!resp) {
     logger.error('No response received from delete request')
-    throw new RetryableError('no response', 503)
+    throw new RetryableError('Remove failed', 503, { operation: 'remove' })
   }
 
-  let result
-  if (typeof resp.body === 'string') {
-    try {
-      result = JSON.parse(resp.body)
-    } catch {
-      result = {}
-    }
-  } else {
-    result = resp.body || {}
+  const result: CouchMutationBody = {
+    ...(isRecord(resp.body) ? resp.body : {})
   }
   result.statusCode = resp.statusCode
 
   if (resp.statusCode === 404) {
     logger.warn(`Document not found for deletion: ${id}`)
-    result.ok = false
-    result.error = 'not_found'
-    return CouchPutResponse.parse(result)
-  }
-
-  if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
-    logger.warn(`Retryable status code received: ${resp.statusCode}`)
-    throw new RetryableError(result.reason || 'retryable error', resp.statusCode)
+    throw new NotFoundError(id, { operation: 'remove', statusCode: resp.statusCode })
   }
 
-  if (resp.statusCode !== 200) {
+  if (!isSuccessStatusCode('documentDelete', resp.statusCode) || !result.ok) {
     logger.error(`Unexpected status code: ${resp.statusCode}`)
-    throw new Error(result.reason || 'failed')
+    throw createResponseError({
+      body: resp.body,
+      defaultMessage: 'Remove failed',
+      docId: id,
+      operation: 'remove',
+      statusCode: resp.statusCode
+    })
   }
 
   logger.info(`Successfully deleted document: ${id}`)