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

package/impl/utils/errors.mts

@@ -1,5 +1,8 @@
+import { getCouchError } from './response.mts'
+import type { StandardSchemaV1 } from '../../types/standard-schema.ts'
+
 /**
- * Represents a network-level error emitted by Node.js or libraries such as `needle`.
+ * Represents a network-level error emitted by Node.js or HTTP client libraries.
  *
  * @public
  */
@@ -15,6 +18,32 @@ export interface NetworkError {
   message?: string
 }
 
+type ErrorWithCause = {
+  cause?: unknown
+}
+
+export type ErrorCategory =
+  | 'conflict'
+  | 'network'
+  | 'not_found'
+  | 'operation'
+  | 'retryable'
+  | 'validation'
+  | 'transaction'
+
+export type ErrorOperation =
+  | 'get'
+  | 'getAtRev'
+  | 'getDBInfo'
+  | 'patch'
+  | 'patchDangerously'
+  | 'put'
+  | 'query'
+  | 'queryStream'
+  | 'remove'
+  | 'request'
+  | 'watchDocs'
+
 const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504])
 
 const NETWORK_ERROR_STATUS_MAP = {
@@ -36,6 +65,69 @@ const isNetworkError = (value: unknown): value is NetworkError & { code: Network
   return typeof candidate.code === 'string' && candidate.code in NETWORK_ERROR_STATUS_MAP
 }
 
+const getNestedNetworkError = (
+  value: unknown
+): (NetworkError & { code: NetworkErrorCode }) | null => {
+  if (isNetworkError(value)) {
+    return value
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return null
+  }
+
+  const candidate = value as ErrorWithCause
+  return isNetworkError(candidate.cause) ? candidate.cause : null
+}
+
+/**
+ * Shared structured fields available on hide-a-bed operational errors.
+ *
+ * @public
+ */
+export type HideABedErrorOptions = {
+  category: ErrorCategory
+  cause?: unknown
+  couchError?: string
+  docId?: string
+  operation?: ErrorOperation
+  retryable: boolean
+  statusCode?: number
+}
+
+/**
+ * Shared base class for operational errors thrown by hide-a-bed.
+ *
+ * @public
+ */
+export class HideABedError extends Error {
+  readonly category: ErrorCategory
+  readonly couchError?: string
+  readonly docId?: string
+  readonly operation?: ErrorOperation
+  readonly retryable: boolean
+  readonly statusCode?: number
+
+  constructor(message: string, options: HideABedErrorOptions) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'HideABedError'
+    this.category = options.category
+    this.couchError = options.couchError
+    this.docId = options.docId
+    this.operation = options.operation
+    this.retryable = options.retryable
+    this.statusCode = options.statusCode
+  }
+}
+
+export type ValidationErrorOptions = Omit<
+  Partial<HideABedErrorOptions>,
+  'category' | 'retryable'
+> & {
+  issues: ReadonlyArray<StandardSchemaV1.Issue>
+  message?: string
+}
+
 /**
  * Error thrown when a requested CouchDB document cannot be found.
  *
@@ -45,22 +137,96 @@ const isNetworkError = (value: unknown): value is NetworkError & { code: Network
  *
  * @public
  */
-export class NotFoundError extends Error {
-  /**
-   * Identifier of the missing document.
-   */
-  readonly docId: string
-
-  /**
-   * 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: string, message = 'Document not found') {
-    super(message)
+export class NotFoundError extends HideABedError {
+  constructor(
+    docId: string,
+    options: Omit<Partial<HideABedErrorOptions>, 'category' | 'docId' | 'retryable'> & {
+      message?: string
+    } = {}
+  ) {
+    super(options.message ?? 'Document not found', {
+      category: 'not_found',
+      couchError: options.couchError ?? 'not_found',
+      cause: options.cause,
+      docId,
+      operation: options.operation,
+      retryable: false,
+      statusCode: options.statusCode ?? 404
+    })
     this.name = 'NotFoundError'
-    this.docId = docId
+  }
+}
+
+/**
+ * Error thrown when a single-document mutation conflicts with the current revision.
+ *
+ * @public
+ */
+export class ConflictError extends HideABedError {
+  constructor(
+    docId: string,
+    options: Omit<Partial<HideABedErrorOptions>, 'category' | 'docId' | 'retryable'> & {
+      message?: string
+    } = {}
+  ) {
+    super(options.message ?? 'Document update conflict', {
+      category: 'conflict',
+      couchError: options.couchError ?? 'conflict',
+      cause: options.cause,
+      docId,
+      operation: options.operation,
+      retryable: false,
+      statusCode: options.statusCode ?? 409
+    })
+    this.name = 'ConflictError'
+  }
+}
+
+/**
+ * Error thrown when an operation fails in a non-retryable way.
+ *
+ * @public
+ */
+export class OperationError extends HideABedError {
+  constructor(
+    message: string,
+    options: Omit<Partial<HideABedErrorOptions>, 'category' | 'retryable'> & {
+      category?: Extract<ErrorCategory, 'operation' | 'transaction'>
+    } = {}
+  ) {
+    super(message, {
+      category: options.category ?? 'operation',
+      cause: options.cause,
+      couchError: options.couchError,
+      docId: options.docId,
+      operation: options.operation,
+      retryable: false,
+      statusCode: options.statusCode
+    })
+    this.name = 'OperationError'
+  }
+}
+
+/**
+ * Error thrown when schema validation fails for a document, row, key, or value.
+ *
+ * @public
+ */
+export class ValidationError extends HideABedError {
+  readonly issues: ValidationErrorOptions['issues']
+
+  constructor(options: ValidationErrorOptions) {
+    super(options.message ?? 'Validation failed', {
+      category: 'validation',
+      cause: options.cause,
+      couchError: options.couchError,
+      docId: options.docId,
+      operation: options.operation,
+      retryable: false,
+      statusCode: options.statusCode
+    })
+    this.name = 'ValidationError'
+    this.issues = options.issues
   }
 }
 
@@ -73,22 +239,24 @@ export class NotFoundError extends Error {
  *
  * @public
  */
-export class RetryableError extends Error {
-  /**
-   * HTTP status code associated with the retryable failure, when available.
-   */
-  readonly statusCode?: number
-
-  /**
-   * 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: string, statusCode?: number) {
-    super(message)
+export class RetryableError extends HideABedError {
+  constructor(
+    message: string,
+    statusCode?: number,
+    options: Omit<Partial<HideABedErrorOptions>, 'category' | 'retryable' | 'statusCode'> & {
+      category?: Extract<ErrorCategory, 'network' | 'retryable'>
+    } = {}
+  ) {
+    super(message, {
+      category: options.category ?? 'retryable',
+      cause: options.cause,
+      couchError: options.couchError,
+      docId: options.docId,
+      operation: options.operation,
+      retryable: true,
+      statusCode
+    })
     this.name = 'RetryableError'
-    this.statusCode = statusCode
   }
 
   /**
@@ -111,11 +279,17 @@ export class RetryableError extends Error {
    * @throws {@link RetryableError} When the error maps to a retryable network condition.
    * @throws {*} Re-throws the original error when it cannot be mapped.
    */
-  static handleNetworkError(err: unknown): never {
-    if (isNetworkError(err)) {
-      const statusCode = NETWORK_ERROR_STATUS_MAP[err.code]
+  static handleNetworkError(err: unknown, operation: ErrorOperation = 'request'): never {
+    const networkError = getNestedNetworkError(err)
+
+    if (networkError) {
+      const statusCode = NETWORK_ERROR_STATUS_MAP[networkError.code]
       if (statusCode) {
-        throw new RetryableError(`Network error: ${err.code}`, statusCode)
+        throw new RetryableError('Network request failed', statusCode, {
+          category: 'network',
+          cause: err,
+          operation
+        })
       }
     }
 
@@ -123,7 +297,59 @@ export class RetryableError extends Error {
   }
 }
 
+type ResponseErrorOptions = {
+  body?: unknown
+  defaultMessage: string
+  docId?: string
+  notFoundMessage?: string
+  operation: ErrorOperation
+  statusCode?: number
+}
+
+export function createResponseError({
+  body,
+  defaultMessage,
+  docId,
+  notFoundMessage,
+  operation,
+  statusCode
+}: ResponseErrorOptions): HideABedError {
+  const couchError = getCouchError(body)
+
+  if (statusCode === 404 && docId) {
+    return new NotFoundError(docId, {
+      couchError,
+      message: notFoundMessage,
+      operation,
+      statusCode
+    })
+  }
+
+  if (statusCode === 409 && docId) {
+    return new ConflictError(docId, {
+      couchError,
+      operation,
+      statusCode
+    })
+  }
+
+  if (RetryableError.isRetryableStatusCode(statusCode)) {
+    return new RetryableError(defaultMessage, statusCode, {
+      couchError,
+      operation
+    })
+  }
+
+  return new OperationError(defaultMessage, {
+    couchError,
+    docId,
+    operation,
+    statusCode
+  })
+}
+
 export function isConflictError(err: unknown): boolean {
+  if (err instanceof ConflictError) return true
   if (typeof err !== 'object' || err === null) return false
   const candidate = err as { statusCode?: unknown }
   return candidate.statusCode === 409

package/impl/utils/fetch.mts

@@ -0,0 +1,201 @@
+import { RetryableError } from './errors.mts'
+import type { RequestOptions } from '../../schema/request.mts'
+import { composeAbortSignal } from './request.mts'
+
+export type HttpMethod = 'DELETE' | 'GET' | 'POST' | 'PUT'
+
+type NativeFetchBody = RequestInit['body']
+
+export type FetchBody =
+  | NativeFetchBody
+  | Record<string, unknown>
+  | Array<unknown>
+  | null
+  | undefined
+
+export type FetchAuth = {
+  password: string
+  username: string
+}
+
+export type FetchResult<TBody> = {
+  body: TBody
+  headers: Headers
+  statusCode: number
+}
+
+export type FetchRequestOptions = {
+  auth?: FetchAuth
+  body?: FetchBody
+  headers?: Record<string, string>
+  method: HttpMethod
+  operation?:
+    | 'get'
+    | 'getAtRev'
+    | 'getDBInfo'
+    | 'patch'
+    | 'patchDangerously'
+    | 'put'
+    | 'query'
+    | 'queryStream'
+    | 'remove'
+    | 'request'
+    | 'watchDocs'
+  request?: RequestOptions
+  signal?: AbortSignal
+  url: string | URL
+}
+
+const JSON_HEADERS = {
+  'Content-Type': 'application/json'
+} as const
+
+const hasHeader = (headers: Record<string, string>, name: string) => {
+  const expected = name.toLowerCase()
+  return Object.keys(headers).some(header => header.toLowerCase() === expected)
+}
+
+const toBasicAuthHeader = ({ username, password }: FetchAuth) => {
+  const token = Buffer.from(`${username}:${password}`).toString('base64')
+  return `Basic ${token}`
+}
+
+const prepareRequest = (options: FetchRequestOptions) => {
+  const auth = options.auth
+  const headers = { ...(options.headers ?? {}) }
+
+  if (auth && !hasHeader(headers, 'Authorization')) {
+    headers.Authorization = toBasicAuthHeader(auth)
+  }
+
+  return { headers }
+}
+
+const isAbortError = (err: unknown): err is DOMException => {
+  return err instanceof DOMException && err.name === 'AbortError'
+}
+
+const isTimeoutError = (err: unknown): err is DOMException => {
+  return err instanceof DOMException && err.name === 'TimeoutError'
+}
+
+const encodeBody = (body: FetchBody): NativeFetchBody | undefined => {
+  if (body == null) return undefined
+
+  if (
+    typeof body === 'string' ||
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body) ||
+    body instanceof Blob ||
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    body instanceof ReadableStream
+  ) {
+    return body as NativeFetchBody
+  }
+
+  return JSON.stringify(body)
+}
+
+const parseJsonResponse = async (response: Response): Promise<unknown> => {
+  if (response.status === 204 || response.status === 205) {
+    return null
+  }
+
+  const text = await response.text()
+
+  if (text.trim() === '') {
+    return null
+  }
+
+  try {
+    return JSON.parse(text)
+  } catch (err) {
+    if (response.ok) {
+      throw err
+    }
+
+    return text
+  }
+}
+
+export async function fetchCouchJson<TBody = unknown>(
+  options: FetchRequestOptions
+): Promise<FetchResult<TBody>> {
+  let response: Response
+  const { headers } = prepareRequest(options)
+  const { signal, timedOut } = composeAbortSignal(options.signal, options.request)
+
+  try {
+    response = await fetch(options.url, {
+      method: options.method,
+      headers: {
+        ...JSON_HEADERS,
+        ...headers
+      },
+      body: encodeBody(options.body),
+      signal,
+      dispatcher: options.request?.dispatcher
+    })
+  } catch (err) {
+    if (timedOut() || isTimeoutError(err)) {
+      throw new RetryableError('Request timed out', 503, {
+        category: 'network',
+        cause: err,
+        operation: options.operation
+      })
+    }
+
+    if (isAbortError(err)) {
+      throw err
+    }
+
+    RetryableError.handleNetworkError(err, options.operation)
+  }
+
+  const body = (await parseJsonResponse(response)) as TBody
+
+  return {
+    body,
+    headers: response.headers,
+    statusCode: response.status
+  }
+}
+
+export async function fetchCouchStream(
+  options: FetchRequestOptions
+): Promise<FetchResult<ReadableStream<Uint8Array> | null>> {
+  let response: Response
+  const { headers } = prepareRequest(options)
+  const { signal, timedOut } = composeAbortSignal(options.signal, options.request)
+
+  try {
+    response = await fetch(options.url, {
+      method: options.method,
+      headers,
+      body: encodeBody(options.body),
+      signal,
+      dispatcher: options.request?.dispatcher
+    })
+  } catch (err) {
+    if (timedOut() || isTimeoutError(err)) {
+      throw new RetryableError('Request timed out', 503, {
+        category: 'network',
+        cause: err,
+        operation: options.operation
+      })
+    }
+
+    if (isAbortError(err)) {
+      throw err
+    }
+
+    RetryableError.handleNetworkError(err, options.operation)
+  }
+
+  return {
+    body: response.body,
+    headers: response.headers,
+    statusCode: response.status
+  }
+}

package/impl/utils/parseRows.mts

@@ -2,9 +2,26 @@
 import { ViewRow } from '../../schema/couch/couch.output.schema.ts'
 import type { StandardSchemaV1 } from '../../types/standard-schema.ts'
 import { z } from 'zod'
+import { OperationError, ValidationError, type ErrorOperation } from './errors.mts'
 
 export type OnInvalidDocAction = 'throw' | 'skip'
 
+const createValidationError = (
+  issues: ReadonlyArray<StandardSchemaV1.Issue>,
+  options: {
+    defaultMessage?: string
+    docId?: string
+    operation?: ErrorOperation
+  }
+) => {
+  return new ValidationError({
+    docId: options.docId,
+    issues,
+    message: options.defaultMessage ?? 'Row validation failed',
+    operation: options.operation ?? 'request'
+  })
+}
+
 export async function parseRows<
   DocSchema extends StandardSchemaV1 = StandardSchemaV1<any>,
   KeySchema extends StandardSchemaV1 = StandardSchemaV1<any>,
@@ -12,14 +29,18 @@ export async function parseRows<
 >(
   rows: unknown,
   options: {
+    defaultMessage?: string
     onInvalidDoc?: OnInvalidDocAction
     docSchema?: DocSchema
     keySchema?: KeySchema
+    operation?: ErrorOperation
     valueSchema?: ValueSchema
   }
 ) {
   if (!Array.isArray(rows)) {
-    throw new Error('invalid rows format')
+    throw new OperationError(options.defaultMessage ?? 'Request failed', {
+      operation: options.operation ?? 'request'
+    })
   }
 
   type ParsedRow = {
@@ -44,14 +65,22 @@ export async function parseRows<
           if (options.keySchema) {
             const parsedKey = await options.keySchema['~standard'].validate(row.key)
             if (parsedKey.issues) {
-              throw parsedKey.issues
+              throw createValidationError(parsedKey.issues, {
+                defaultMessage: options.defaultMessage,
+                docId: typeof row.id === 'string' ? row.id : undefined,
+                operation: options.operation
+              })
             }
             parsedRow.key = parsedKey.value
           }
           if (options.valueSchema) {
             const parsedValue = await options.valueSchema['~standard'].validate(row.value)
             if (parsedValue.issues) {
-              throw parsedValue.issues
+              throw createValidationError(parsedValue.issues, {
+                defaultMessage: options.defaultMessage,
+                docId: typeof row.id === 'string' ? row.id : undefined,
+                operation: options.operation
+              })
             }
             parsedRow.value = parsedValue.value
           }
@@ -70,7 +99,11 @@ export async function parseRows<
               return 'skip'
             } else {
               // throw by default
-              throw parsedDocRes.issues
+              throw createValidationError(parsedDocRes.issues, {
+                defaultMessage: options.defaultMessage,
+                docId: typeof row.id === 'string' ? row.id : undefined,
+                operation: options.operation
+              })
             }
           } else {
             parsedDoc = parsedDocRes.value
@@ -80,7 +113,11 @@ export async function parseRows<
         if (options.keySchema) {
           const parsedKeyRes = await options.keySchema['~standard'].validate(row.key)
           if (parsedKeyRes.issues) {
-            throw parsedKeyRes.issues
+            throw createValidationError(parsedKeyRes.issues, {
+              defaultMessage: options.defaultMessage,
+              docId: typeof row.id === 'string' ? row.id : undefined,
+              operation: options.operation
+            })
           } else {
             parsedKey = parsedKeyRes.value
           }
@@ -89,7 +126,11 @@ export async function parseRows<
         if (options.valueSchema) {
           const parsedValueRes = await options.valueSchema['~standard'].validate(row.value)
           if (parsedValueRes.issues) {
-            throw parsedValueRes.issues
+            throw createValidationError(parsedValueRes.issues, {
+              defaultMessage: options.defaultMessage,
+              docId: typeof row.id === 'string' ? row.id : undefined,
+              operation: options.operation
+            })
           } else {
             parsedValue = parsedValueRes.value
           }

package/impl/utils/request.mts

@@ -0,0 +1,22 @@
+import type { RequestOptions } from '../../schema/request.mts'
+
+const definedSignals = (signals: Array<AbortSignal | undefined>): AbortSignal[] => {
+  return signals.filter((signal): signal is AbortSignal => signal != null)
+}
+
+export const composeAbortSignal = (
+  internalSignal?: AbortSignal,
+  request?: RequestOptions
+): {
+  signal: AbortSignal | undefined
+  timedOut: () => boolean
+} => {
+  const timeoutSignal =
+    typeof request?.timeout === 'number' ? AbortSignal.timeout(request.timeout) : undefined
+  const signals = definedSignals([internalSignal, request?.signal, timeoutSignal])
+
+  return {
+    signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
+    timedOut: () => timeoutSignal?.aborted === true
+  }
+}