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

package/impl/sugar/watch.test.mts

@@ -0,0 +1,155 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { EventEmitter } from 'node:events'
+import needle from 'needle'
+import type { CouchConfigInput } from '../../schema/config.mts'
+import { watchDocs } from './watch.mts'
+
+class FakeRequest extends EventEmitter {
+  destroyed = false
+
+  destroy() {
+    this.destroyed = true
+    this.emit('close')
+  }
+}
+
+type NeedleRequest = ReturnType<typeof needle.get>
+
+const baseConfig = (): CouchConfigInput => ({
+  couch: 'http://localhost:5984/watch-test'
+})
+
+const waitFor = async (predicate: () => boolean, timeoutMs = 2000, intervalMs = 10) => {
+  const startedAt = Date.now()
+  while (Date.now() - startedAt <= timeoutMs) {
+    if (predicate()) return
+    await new Promise(resolve => {
+      setTimeout(resolve, intervalMs)
+    })
+  }
+  throw new Error('waitFor timed out')
+}
+
+suite('watchDocs', () => {
+  test('requires at least one document id', () => {
+    assert.throws(() => {
+      watchDocs(baseConfig(), [], () => {})
+    }, /non-empty array/)
+  })
+
+  test('rejects more than 100 document ids', () => {
+    const ids = Array.from({ length: 101 }, (_, index) => `doc-${index}`)
+    assert.throws(() => {
+      watchDocs(baseConfig(), ids, () => {})
+    }, /100 or fewer elements/)
+  })
+
+  test('emits change events for streamed chunks', async t => {
+    const requests: FakeRequest[] = []
+    const getMock = t.mock.method(needle, 'get', () => {
+      const request = new FakeRequest()
+      requests.push(request)
+      return request as unknown as NeedleRequest
+    })
+    t.after(() => {
+      getMock.mock.restore()
+    })
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const changes: any[] = []
+    const watcher = watchDocs(
+      baseConfig(),
+      ['doc-a', 'doc-b'],
+      change => {
+        changes.push(change)
+      },
+      { include_docs: true }
+    )
+
+    await waitFor(() => requests.length === 1)
+    const firstRequest = requests[0]
+
+    firstRequest.emit('data', Buffer.from('{"id":"doc-a","seq":"1"}\n{"id":"doc-b","seq":"2"}\n'))
+
+    await waitFor(() => changes.length === 2)
+
+    assert.deepStrictEqual(
+      changes.map(change => change.id),
+      ['doc-a', 'doc-b']
+    )
+    const firstArg = getMock.mock.calls[0].arguments[0]
+    if (typeof firstArg !== 'string') {
+      throw new Error('Expected first argument to be a string')
+    }
+    assert.match(firstArg, /include_docs=true/)
+    assert.match(firstArg, /doc_ids=\["doc-a","doc-b"\]/)
+
+    watcher.stop()
+  })
+
+  test('reconnects after retryable response status', async t => {
+    const requests: FakeRequest[] = []
+    const getMock = t.mock.method(needle, 'get', () => {
+      const request = new FakeRequest()
+      requests.push(request)
+      return request as unknown as NeedleRequest
+    })
+    t.after(() => {
+      getMock.mock.restore()
+    })
+
+    const watcher = watchDocs(baseConfig(), 'doc-retry', () => {}, {
+      initialDelay: 1,
+      maxDelay: 1,
+      maxRetries: 3
+    })
+
+    await waitFor(() => requests.length === 1)
+    const firstRequest = requests[0]
+    firstRequest.emit('response', { statusCode: 503 })
+
+    await waitFor(() => requests.length === 2)
+
+    assert.ok(firstRequest.destroyed)
+    assert.strictEqual(getMock.mock.callCount(), 2)
+
+    watcher.stop()
+  })
+
+  test('emits error after exhausting retries', async t => {
+    const requests: FakeRequest[] = []
+    const getMock = t.mock.method(needle, 'get', () => {
+      const request = new FakeRequest()
+      requests.push(request)
+      return request as unknown as NeedleRequest
+    })
+    t.after(() => {
+      getMock.mock.restore()
+    })
+
+    const errors: Error[] = []
+    const watcher = watchDocs(baseConfig(), 'doc-max', () => {}, {
+      maxRetries: 2,
+      initialDelay: 1,
+      maxDelay: 1
+    })
+    watcher.on('error', err => {
+      errors.push(err as unknown as Error)
+    })
+
+    await waitFor(() => requests.length === 1)
+    requests[0].emit('error', { code: 'ECONNRESET' })
+
+    await waitFor(() => requests.length === 2)
+    requests[1].emit('error', { code: 'ECONNRESET' })
+
+    await waitFor(() => requests.length === 3)
+    requests[2].emit('error', { code: 'ECONNRESET' })
+
+    await waitFor(() => errors.length === 1)
+    assert.strictEqual(errors[0].message, 'Max retries reached')
+
+    watcher.stop()
+  })
+})

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/errors.test.mts

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { NotFoundError, RetryableError, isConflictError } from './errors.mts'
+
+suite('errors', () => {
+  test('NotFoundError exposes docId and message', () => {
+    const err = new NotFoundError('doc-123')
+    assert.strictEqual(err.name, 'NotFoundError')
+    assert.strictEqual(err.message, 'Document not found')
+    assert.strictEqual(err.docId, 'doc-123')
+  })
+
+  test('NotFoundError accepts custom message', () => {
+    const err = new NotFoundError('doc-456', 'missing doc')
+    assert.strictEqual(err.message, 'missing doc')
+  })
+
+  test('RetryableError.isRetryableStatusCode identifies retryable statuses', () => {
+    const retryable = [408, 429, 500, 502, 503, 504]
+    for (const status of retryable) {
+      assert.strictEqual(RetryableError.isRetryableStatusCode(status), true)
+    }
+    assert.strictEqual(RetryableError.isRetryableStatusCode(404), false)
+    assert.strictEqual(RetryableError.isRetryableStatusCode(undefined), false)
+  })
+
+  test('handleNetworkError wraps known network failures', () => {
+    assert.throws(
+      () => RetryableError.handleNetworkError({ code: 'ECONNRESET' }),
+      (err: unknown) =>
+        err instanceof RetryableError &&
+        err.statusCode === 503 &&
+        err.message.includes('ECONNRESET')
+    )
+  })
+
+  test('handleNetworkError rethrows unknown errors', () => {
+    const original = new Error('boom')
+    assert.throws(
+      () => RetryableError.handleNetworkError(original),
+      (err: unknown) => err === original
+    )
+  })
+
+  test('handleNetworkError rethrows unrecognized network codes', () => {
+    const networkErr = { code: 'UNKNOWN' }
+    assert.throws(
+      () => RetryableError.handleNetworkError(networkErr),
+      (err: unknown) => err === networkErr
+    )
+  })
+
+  test('isConflictError detects statusCode 409', () => {
+    assert.strictEqual(isConflictError({ statusCode: 409 }), true)
+    assert.strictEqual(isConflictError({ statusCode: 412 }), false)
+    assert.strictEqual(isConflictError(null), false)
+  })
+})

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/logger.test.mts

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import type { CouchConfigInput } from '../../schema/config.mts'
+import { createLogger, type Logger } from './logger.mts'
+
+const baseConfig = (): CouchConfigInput => ({
+  couch: 'http://localhost:5984'
+})
+
+suite('createLogger', () => {
+  test('returns cached logger when present', () => {
+    const cached: Logger = {
+      error: () => {},
+      warn: () => {},
+      info: () => {},
+      debug: () => {}
+    }
+    const config: CouchConfigInput = {
+      ...baseConfig(),
+      '~normalizedLogger': cached
+    }
+
+    const logger = createLogger(config)
+
+    assert.strictEqual(logger, cached)
+  })
+
+  test('uses console logger when requested', () => {
+    const errorCalls: unknown[][] = []
+    const warnCalls: unknown[][] = []
+    const infoCalls: unknown[][] = []
+    const debugCalls: unknown[][] = []
+
+    const originalError = console.error
+    const originalWarn = console.warn
+    const originalInfo = console.info
+    const originalDebug = console.debug
+
+    console.error = (...args: unknown[]) => {
+      errorCalls.push(args)
+    }
+    console.warn = (...args: unknown[]) => {
+      warnCalls.push(args)
+    }
+    console.info = (...args: unknown[]) => {
+      infoCalls.push(args)
+    }
+    console.debug = (...args: unknown[]) => {
+      debugCalls.push(args)
+    }
+
+    try {
+      const config: CouchConfigInput = {
+        ...baseConfig(),
+        useConsoleLogger: true
+      }
+
+      const logger = createLogger(config)
+
+      logger.error('boom')
+      logger.warn('warn', 123)
+      logger.info('info')
+      logger.debug('debug')
+
+      assert.strictEqual(config['~normalizedLogger'], logger)
+      assert.deepStrictEqual(errorCalls, [['boom']])
+      assert.deepStrictEqual(warnCalls, [['warn', 123]])
+      assert.deepStrictEqual(infoCalls, [['info']])
+      assert.deepStrictEqual(debugCalls, [['debug']])
+    } finally {
+      console.error = originalError
+      console.warn = originalWarn
+      console.info = originalInfo
+      console.debug = originalDebug
+    }
+  })
+
+  test('creates no-op logger when none provided', () => {
+    const config = baseConfig()
+    const logger = createLogger(config)
+
+    assert.strictEqual(config['~normalizedLogger'], logger)
+    assert.doesNotThrow(() => logger.error('noop'))
+    assert.doesNotThrow(() => logger.warn('noop'))
+    assert.doesNotThrow(() => logger.info('noop'))
+    assert.doesNotThrow(() => logger.debug('noop'))
+  })
+
+  test('wraps function logger', () => {
+    const calls: Array<{ level: string; args: unknown[] }> = []
+    const fnLogger = (level: string, ...args: unknown[]) => {
+      calls.push({ level, args })
+    }
+
+    const config: CouchConfigInput = {
+      ...baseConfig(),
+      logger: fnLogger
+    }
+
+    const logger = createLogger(config)
+    logger.info('hello', 42)
+    logger.error('problem')
+
+    assert.deepStrictEqual(calls, [
+      { level: 'info', args: ['hello', 42] },
+      { level: 'error', args: ['problem'] }
+    ])
+  })
+
+  test('fills missing methods on object logger', () => {
+    let warnCount = 0
+    const config: CouchConfigInput = {
+      ...baseConfig(),
+      logger: {
+        warn: () => {
+          warnCount++
+        }
+      }
+    }
+
+    const logger = createLogger(config)
+    logger.warn('watch out')
+
+    assert.strictEqual(warnCount, 1)
+    assert.doesNotThrow(() => logger.error('ignored'))
+    assert.doesNotThrow(() => logger.info('ignored'))
+    assert.doesNotThrow(() => logger.debug('ignored'))
+  })
+})

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)
+}