hide-a-bed 5.2.8 → 6.0.0

package/impl/sugar/{watch.mjs → watch.mts}

@@ -1,18 +1,43 @@
 import needle from 'needle'
 import { EventEmitter } from 'events'
-import { RetryableError } from '../errors.mjs'
-import { createLogger } from '../logger.mjs'
-import { sleep } from '../patch.mjs'
-import { WatchDocs } from '../../schema/sugar/watch.mjs'
-
-// watch the doc for any changes
-export const watchDocs = WatchDocs.implement((config, docIds, onChange, options = {}) => {
+import { RetryableError } from '../utils/errors.mts'
+import { createLogger } from '../utils/logger.mts'
+import { WatchOptions, type WatchOptionsInput } from '../../schema/sugar/watch.mts'
+import { mergeNeedleOpts } from '../utils/mergeNeedleOpts.mts'
+import { setTimeout } from 'node:timers/promises'
+import {
+  CouchConfig,
+  type CouchConfigInput,
+  type NeedleBaseOptionsSchema
+} from '../../schema/config.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
+ */
+export function watchDocs(
+  configInput: CouchConfigInput,
+  docIds: string | string[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onChange: (change: any) => void,
+  optionsInput: WatchOptionsInput = {}
+) {
+  const config = CouchConfig.parse(configInput)
+  const options = WatchOptions.parse(optionsInput)
   const logger = createLogger(config)
   const emitter = new EventEmitter()
-  let lastSeq = null || 'now'
+  let lastSeq: null | 'now' = null
   let stopping = false
   let retryCount = 0
-  let currentRequest = null
+  let currentRequest: null | ReturnType<typeof needle.get> = null
   const maxRetries = options.maxRetries || 10
   const initialDelay = options.initialDelay || 1000
   const maxDelay = options.maxDelay || 30000
@@ -29,13 +54,17 @@ export const watchDocs = WatchDocs.implement((config, docIds, onChange, options
     const ids = _docIds.join('","')
     const url = `${config.couch}/_changes?feed=${feed}&since=${lastSeq}&include_docs=${includeDocs}&filter=_doc_ids&doc_ids=["${ids}"]`
 
-    const opts = {
-      headers: { 'Content-Type': 'application/json' },
+    const opts: NeedleBaseOptionsSchema = {
+      json: false,
+      headers: {
+        'Content-Type': 'application/json'
+      },
       parse_response: false
     }
+    const mergedOpts = mergeNeedleOpts(config, opts)
 
     let buffer = ''
-    currentRequest = needle.get(url, opts)
+    currentRequest = needle.get(url, mergedOpts)
 
     currentRequest.on('data', chunk => {
       buffer += chunk.toString()
@@ -61,13 +90,16 @@ export const watchDocs = WatchDocs.implement((config, docIds, onChange, options
     })
 
     currentRequest.on('response', response => {
-      logger.debug(`Received response with status code, watching [${_docIds}]: ${response.statusCode}`)
+      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.abort()
+        // @ts-expect-error bad type?
+        currentRequest?.destroy()
         handleReconnect()
       } else {
-      // Reset retry count on successful connection
+        // Reset retry count on successful connection
         retryCount = 0
       }
     })
@@ -85,14 +117,14 @@ export const watchDocs = WatchDocs.implement((config, docIds, onChange, options
           logger.info(`Retryable error, watching [${_docIds}]:`, filteredError.toString())
           handleReconnect()
         } else {
-          logger.error(`Non-retryable error, watching [${_docIds}]`, filteredError.toString())
+          logger.error(`Non-retryable error, watching [${_docIds}]`, filteredError?.toString())
           emitter.emit('error', filteredError)
         }
       }
     })
 
     currentRequest.on('end', () => {
-    // Process any remaining data in buffer
+      // Process any remaining data in buffer
       if (buffer.trim()) {
         try {
           const change = JSON.parse(buffer)
@@ -125,7 +157,7 @@ export const watchDocs = WatchDocs.implement((config, docIds, onChange, options
     retryCount++
 
     logger.info(`Attempting to reconnect in ${delay}ms (attempt ${retryCount} of ${maxRetries})`)
-    await sleep(delay)
+    await setTimeout(delay)
 
     try {
       connect()
@@ -142,13 +174,15 @@ export const watchDocs = WatchDocs.implement((config, docIds, onChange, options
   emitter.on('change', onChange)
 
   return {
-    on: (event, listener) => emitter.on(event, listener),
-    removeListener: (event, listener) => emitter.removeListener(event, listener),
+    on: (event: string, listener: EventListener) => emitter.on(event, listener),
+    removeListener: (event: string, listener: EventListener) =>
+      emitter.removeListener(event, listener),
     stop: () => {
       stopping = true
-      if (currentRequest) currentRequest.abort()
+      // @ts-expect-error bad type?
+      if (currentRequest) currentRequest.destroy()
       emitter.emit('end', { lastSeq })
       emitter.removeAllListeners()
     }
   }
-})
+}

package/impl/utils/errors.mts

@@ -0,0 +1,130 @@
+/**
+ * Represents a network-level error emitted by Node.js or libraries such as `needle`.
+ *
+ * @public
+ */
+export interface NetworkError {
+  /**
+   * Machine-readable error code describing the network failure.
+   */
+  code: string
+
+  /**
+   * Optional human-readable message supplied by the underlying library.
+   */
+  message?: string
+}
+
+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
+} as const satisfies Record<string, number>
+
+type NetworkErrorCode = keyof typeof NETWORK_ERROR_STATUS_MAP
+
+const isNetworkError = (value: unknown): value is NetworkError & { code: NetworkErrorCode } => {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as { code?: unknown }
+  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
+ */
+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)
+    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
+ */
+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)
+    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: number | undefined): statusCode is number {
+    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: unknown): never {
+    if (isNetworkError(err)) {
+      const statusCode = NETWORK_ERROR_STATUS_MAP[err.code]
+      if (statusCode) {
+        throw new RetryableError(`Network error: ${err.code}`, statusCode)
+      }
+    }
+
+    throw err
+  }
+}
+
+export function isConflictError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false
+  const candidate = err as { statusCode?: unknown }
+  return candidate.statusCode === 409
+}

package/impl/utils/logger.mts

@@ -0,0 +1,62 @@
+import type { CouchConfigInput } from '../../schema/config.mts'
+
+type LoggerMethod = (...args: unknown[]) => void
+
+export type Logger = {
+  error: LoggerMethod
+  warn: LoggerMethod
+  info: LoggerMethod
+  debug: LoggerMethod
+}
+
+type FunctionLogger = (level: keyof Logger, ...args: unknown[]) => void
+
+const noop: LoggerMethod = () => {}
+
+const createConsoleLogger = (): Logger => ({
+  error: (...args) => console.error(...args),
+  warn: (...args) => console.warn(...args),
+  info: (...args) => console.info(...args),
+  debug: (...args) => console.debug(...args)
+})
+
+const createNoopLogger = (): Logger => ({
+  error: noop,
+  warn: noop,
+  info: noop,
+  debug: noop
+})
+
+export function createLogger(config: CouchConfigInput): Logger {
+  if (config['~normalizedLogger']) {
+    return config['~normalizedLogger']
+  }
+
+  if (!config.logger) {
+    const normalized = config.useConsoleLogger ? createConsoleLogger() : createNoopLogger()
+    config['~normalizedLogger'] = normalized
+    return normalized
+  }
+
+  if (typeof config.logger === 'function') {
+    const loggerFn = config.logger as FunctionLogger
+    const normalized: Logger = {
+      error: (...args) => loggerFn('error', ...args),
+      warn: (...args) => loggerFn('warn', ...args),
+      info: (...args) => loggerFn('info', ...args),
+      debug: (...args) => loggerFn('debug', ...args)
+    }
+    config['~normalizedLogger'] = normalized
+    return normalized
+  }
+
+  const loggerObj = config.logger as Partial<Logger>
+  const normalized: Logger = {
+    error: loggerObj.error ?? noop,
+    warn: loggerObj.warn ?? noop,
+    info: loggerObj.info ?? noop,
+    debug: loggerObj.debug ?? noop
+  }
+  config['~normalizedLogger'] = normalized
+  return normalized
+}

package/impl/utils/mergeNeedleOpts.mts

@@ -0,0 +1,16 @@
+import { MergeNeedleOpts } from '../../schema/util.mts'
+
+export const mergeNeedleOpts = MergeNeedleOpts.implement((config, opts) => {
+  if (config.needleOpts) {
+    return {
+      ...opts,
+      ...config.needleOpts,
+      headers: {
+        ...opts.headers,
+        ...(config.needleOpts.headers ?? {})
+      }
+    }
+  }
+
+  return opts
+})

package/impl/utils/parseRows.mts

@@ -0,0 +1,117 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ViewRow } from '../../schema/couch/couch.output.schema.ts'
+import type { StandardSchemaV1 } from '../../types/standard-schema.ts'
+import { z } from 'zod'
+
+export type OnInvalidDocAction = 'throw' | 'skip'
+
+export async function parseRows<
+  DocSchema extends StandardSchemaV1 = StandardSchemaV1<any>,
+  KeySchema extends StandardSchemaV1 = StandardSchemaV1<any>,
+  ValueSchema extends StandardSchemaV1 = StandardSchemaV1<any>
+>(
+  rows: unknown,
+  options: {
+    onInvalidDoc?: OnInvalidDocAction
+    docSchema?: DocSchema
+    keySchema?: KeySchema
+    valueSchema?: ValueSchema
+  }
+) {
+  if (!Array.isArray(rows)) {
+    throw new Error('invalid rows format')
+  }
+
+  type ParsedRow = {
+    id?: string
+    key?: StandardSchemaV1.InferOutput<KeySchema>
+    value?: StandardSchemaV1.InferOutput<ValueSchema>
+    doc?: StandardSchemaV1.InferOutput<DocSchema>
+    error?: string
+  }
+  type RowResult = ParsedRow | 'skip'
+  const isFinalRow = (row: RowResult): row is ParsedRow => row !== 'skip'
+
+  const parsedRows: Array<RowResult> = await Promise.all(
+    rows.map(async (row: any) => {
+      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.looseObject(ViewRow.shape).parse(row)
+          if (options.keySchema) {
+            const parsedKey = await options.keySchema['~standard'].validate(row.key)
+            if (parsedKey.issues) {
+              throw parsedKey.issues
+            }
+            parsedRow.key = parsedKey.value
+          }
+          if (options.valueSchema) {
+            const parsedValue = await options.valueSchema['~standard'].validate(row.value)
+            if (parsedValue.issues) {
+              throw parsedValue.issues
+            }
+            parsedRow.value = parsedValue.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') {
+              // skip invalid doc
+              return 'skip'
+            } else {
+              // throw by default
+              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') {
+          // skip invalid doc
+          return 'skip'
+        } else {
+          // throw by default
+          throw e
+        }
+      }
+    })
+  )
+
+  return parsedRows.filter(isFinalRow)
+}

package/impl/utils/queryBuilder.mts

@@ -0,0 +1,173 @@
+import type { ViewOptions } from '../../schema/couch/couch.input.schema.ts'
+
+/**
+ * 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.
+ */
+export class QueryBuilder {
+  #options: ViewOptions = {}
+
+  descending(descending = true): this {
+    this.#options.descending = descending
+    return this
+  }
+
+  endkey_docid(endkeyDocId: NonNullable<ViewOptions['endkey_docid']>): this {
+    this.#options.endkey_docid = endkeyDocId
+    return this
+  }
+
+  /**
+   * Alias for endkey_docid
+   */
+  end_key_doc_id(endkeyDocId: NonNullable<ViewOptions['endkey_docid']>): this {
+    this.#options.endkey_docid = endkeyDocId
+    return this
+  }
+
+  endkey(endkey: ViewOptions['endkey']): this {
+    this.#options.endkey = endkey
+    return this
+  }
+
+  /**
+   * Alias for endkey
+   */
+  endKey(endkey: ViewOptions['endkey']): this {
+    this.#options.endkey = endkey
+    return this
+  }
+
+  /**
+   * Alias for endkey
+   */
+  end_key(endkey: ViewOptions['endkey']): this {
+    this.#options.endkey = endkey
+    return this
+  }
+
+  group(group = true): this {
+    this.#options.group = group
+    return this
+  }
+
+  group_level(level: NonNullable<ViewOptions['group_level']>): this {
+    this.#options.group_level = level
+    return this
+  }
+
+  include_docs(includeDocs = true): this {
+    this.#options.include_docs = includeDocs
+    return this
+  }
+
+  inclusive_end(inclusiveEnd = true): this {
+    this.#options.inclusive_end = inclusiveEnd
+    return this
+  }
+
+  key(key: ViewOptions['key']): this {
+    this.#options.key = key
+    return this
+  }
+
+  keys(keys: NonNullable<ViewOptions['keys']>): this {
+    this.#options.keys = keys
+    return this
+  }
+
+  limit(limit: NonNullable<ViewOptions['limit']>): this {
+    this.#options.limit = limit
+    return this
+  }
+
+  reduce(reduce = true): this {
+    this.#options.reduce = reduce
+    return this
+  }
+
+  skip(skip: NonNullable<ViewOptions['skip']>): this {
+    this.#options.skip = skip
+    return this
+  }
+
+  sorted(sorted = true): this {
+    this.#options.sorted = sorted
+    return this
+  }
+
+  stable(stable = true): this {
+    this.#options.stable = stable
+    return this
+  }
+
+  startkey(startkey: ViewOptions['startkey']): this {
+    this.#options.startkey = startkey
+    return this
+  }
+
+  /**
+   * Alias for startkey
+   */
+  startKey(startkey: ViewOptions['startkey']): this {
+    this.#options.startkey = startkey
+    return this
+  }
+
+  /**
+   * Alias for startkey
+   */
+  start_key(startkey: ViewOptions['startkey']): this {
+    this.#options.startkey = startkey
+    return this
+  }
+
+  startkey_docid(startkeyDocId: NonNullable<ViewOptions['startkey_docid']>): this {
+    this.#options.startkey_docid = startkeyDocId
+    return this
+  }
+
+  /**
+   * Alias for startkey_docid
+   */
+  start_key_doc_id(startkeyDocId: NonNullable<ViewOptions['startkey_docid']>): this {
+    this.#options.startkey_docid = startkeyDocId
+    return this
+  }
+
+  update(update: NonNullable<ViewOptions['update']>): this {
+    this.#options.update = update
+    return this
+  }
+
+  update_seq(updateSeq = true): this {
+    this.#options.update_seq = updateSeq
+    return this
+  }
+
+  /**
+   * Builds and returns the ViewOptions object.
+   */
+  build(): ViewOptions {
+    return { ...this.#options }
+  }
+}
+
+type AssertViewOptionsCovered =
+  Exclude<keyof ViewOptions, keyof QueryBuilder> extends never ? true : never
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _assertViewOptionsCovered: AssertViewOptionsCovered = true
+
+export const createQuery = (): QueryBuilder => new QueryBuilder()

package/impl/utils/queryString.mts

@@ -0,0 +1,44 @@
+import { ViewOptions } from '../../schema/couch/couch.input.schema.ts'
+
+const KEYS_TO_QUOTE: (keyof ViewOptions)[] = [
+  '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
+ */
+export function queryString(options: ViewOptions = {}): string {
+  const searchParams = new URLSearchParams()
+  const parsedOptions = ViewOptions.parse(options)
+  Object.entries(parsedOptions).forEach(([key, rawValue]) => {
+    let value = rawValue
+    if (KEYS_TO_QUOTE.includes(key as keyof ViewOptions)) {
+      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()
+}