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

package/impl/query.test.mts

@@ -0,0 +1,280 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import { randomUUID } from 'node:crypto'
+import { setTimeout as delay } from 'node:timers/promises'
+import { z } from 'zod'
+
+import type { CouchConfigInput } from '../schema/config.mts'
+import { TEST_DB_URL } from '../test/setup-db.mts'
+import { query } from './query.mts'
+import { RetryableError } from './utils/errors.mts'
+
+const config: CouchConfigInput = {
+  couch: TEST_DB_URL
+}
+
+async function putDoc(doc: Record<string, unknown> & { _id: string }) {
+  await needle('put', `${TEST_DB_URL}/${doc._id}`, doc, { json: true })
+}
+
+async function putDesignDoc(id: string, viewName: string, mapFn: string) {
+  await needle(
+    'put',
+    `${TEST_DB_URL}/_design/${id}`,
+    {
+      views: {
+        [viewName]: {
+          map: mapFn
+        }
+      }
+    },
+    { json: true }
+  )
+}
+
+async function eventually<T>(
+  fn: () => Promise<T>,
+  predicate: (value: T) => boolean,
+  attempts = 10,
+  waitMs = 100
+): Promise<T> {
+  let lastValue: T | undefined
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    lastValue = await fn()
+    if (predicate(lastValue)) return lastValue
+    await delay(waitMs)
+  }
+  return lastValue!
+}
+
+suite('query', () => {
+  test('returns rows with include_docs', async () => {
+    const designId = `query-view-${randomUUID()}`
+    const viewName = 'byCategory'
+    const tag = `query-suite-${randomUUID()}`
+    await putDesignDoc(
+      designId,
+      viewName,
+      `function(doc) { if (doc.tag !== '${tag}') return; emit(doc.category, doc.count); }`
+    )
+
+    const matchingDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      category: 'keep',
+      count: 42
+    }
+    const otherDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      category: 'skip',
+      count: 1
+    }
+    const unrelatedDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag: 'other',
+      category: 'keep',
+      count: 100
+    }
+
+    await putDoc(matchingDoc)
+    await putDoc(otherDoc)
+    await putDoc(unrelatedDoc)
+
+    const response = await eventually(
+      () =>
+        query(config, `_design/${designId}/_view/${viewName}`, {
+          include_docs: true,
+          key: matchingDoc.category
+        }),
+      ({ rows }) => rows?.length === 1
+    )
+
+    if (!response.rows) {
+      throw new Error('Expected rows in response')
+    }
+
+    assert.strictEqual(response.rows[0].key, matchingDoc.category)
+    assert.strictEqual(response.rows[0].value, matchingDoc.count)
+    assert.strictEqual(response.rows[0].doc?._id, matchingDoc._id)
+  })
+
+  test('validates rows when schemas provided', async () => {
+    const designId = `query-validate-${randomUUID()}`
+    const viewName = 'byPlayer'
+    const tag = `query-suite-${randomUUID()}`
+    await putDesignDoc(
+      designId,
+      viewName,
+      `function(doc) { if (doc.tag !== '${tag}') return; emit(doc.player, doc.score); }`
+    )
+
+    const doc = { _id: `doc-${randomUUID()}`, tag, player: 'alpha', score: 7 }
+    await putDoc(doc)
+
+    const response = await eventually(
+      () =>
+        query(config, `_design/${designId}/_view/${viewName}`, {
+          include_docs: true,
+          key: doc.player,
+          validate: {
+            docSchema: z.looseObject({
+              _id: z.string(),
+              tag: z.string(),
+              player: z.string(),
+              score: z.number()
+            }),
+            keySchema: z.string(),
+            valueSchema: z.number()
+          }
+        }),
+      ({ rows }) => rows.length === 1
+    )
+
+    assert.strictEqual(response.rows[0]?.value, doc.score)
+    assert.strictEqual(response.rows[0]?.doc?.player, doc.player)
+  })
+
+  test('rejects when validation fails', async () => {
+    const designId = `query-invalid-${randomUUID()}`
+    const viewName = 'byPlayer'
+    const tag = `query-suite-${randomUUID()}`
+    await putDesignDoc(
+      designId,
+      viewName,
+      `function(doc) { if (doc.tag !== '${tag}') return; emit(doc.player, doc.score); }`
+    )
+
+    const validDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      player: 'valid',
+      score: 3
+    }
+    const invalidDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      player: 'invalid',
+      score: 'nope'
+    }
+
+    await putDoc(validDoc)
+    await putDoc(invalidDoc)
+
+    await eventually(
+      () =>
+        query(config, `_design/${designId}/_view/${viewName}`, {
+          key: validDoc.player
+        }),
+      ({ rows }) => rows?.length === 1
+    )
+
+    await assert.rejects(async () => {
+      return query(config, `_design/${designId}/_view/${viewName}`, {
+        validate: {
+          valueSchema: z.number()
+        }
+      })
+    })
+  })
+
+  test('skips invalid documents when onInvalidDoc=skip', async () => {
+    const designId = `query-skip-${randomUUID()}`
+    const viewName = 'byPlayer'
+    const tag = `query-suite-${randomUUID()}`
+    await putDesignDoc(
+      designId,
+      viewName,
+      `function(doc) { if (doc.tag !== '${tag}') return; emit(doc.player, doc.score); }`
+    )
+
+    const validDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      player: 'valid',
+      score: 5
+    }
+    const invalidDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      player: 'invalid',
+      score: 'nope'
+    }
+
+    await putDoc(validDoc)
+    await putDoc(invalidDoc)
+
+    const response = await eventually(
+      () =>
+        query(config, `_design/${designId}/_view/${viewName}`, {
+          include_docs: true,
+          validate: {
+            docSchema: z.looseObject({
+              _id: z.string(),
+              tag: z.string(),
+              player: z.string(),
+              score: z.number()
+            }),
+            keySchema: z.string(),
+            valueSchema: z.number(),
+            onInvalidDoc: 'skip'
+          }
+        }),
+      ({ rows }) => rows.length === 1
+    )
+
+    assert.strictEqual(response.rows[0]?.doc?.player, validDoc.player)
+  })
+
+  test('posts payload when keys exceed URL limit', async () => {
+    const designId = `query-post-${randomUUID()}`
+    const viewName = 'byPlayer'
+    const tag = `query-suite-${randomUUID()}`
+    await putDesignDoc(
+      designId,
+      viewName,
+      `function(doc) { if (doc.tag !== '${tag}') return; emit(doc.player, doc.score); }`
+    )
+
+    const targetDoc = {
+      _id: `doc-${randomUUID()}`,
+      tag,
+      player: 'target',
+      score: 11
+    }
+    await putDoc(targetDoc)
+
+    await eventually(
+      () =>
+        query(config, `_design/${designId}/_view/${viewName}`, {
+          key: targetDoc.player
+        }),
+      ({ rows }) => rows?.length === 1
+    )
+
+    const bulkKeys = Array.from({ length: 400 }, (_, index) => `missing-${index}-${randomUUID()}`)
+    bulkKeys.push(targetDoc.player)
+
+    const response = await query(config, `_design/${designId}/_view/${viewName}`, {
+      include_docs: true,
+      keys: bulkKeys
+    })
+
+    if (!response.rows) throw new Error('Expected rows in response')
+    assert.strictEqual(response.rows.length, 1)
+    assert.strictEqual(response.rows[0]?.key, targetDoc.player)
+    assert.strictEqual(response.rows[0]?.doc?._id, targetDoc._id)
+  })
+
+  test('throws RetryableError on network failure', async () => {
+    const offlineConfig: CouchConfigInput = {
+      couch: 'http://localhost:6553/offline-db'
+    }
+
+    await assert.rejects(
+      () => query(offlineConfig, '_all_docs', {}),
+      (err: unknown) => err instanceof RetryableError && err.statusCode === 503
+    )
+  })
+})

package/impl/remove.mts

@@ -0,0 +1,65 @@
+import needle from 'needle'
+import { createLogger } from './utils/logger.mts'
+import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
+import { RetryableError } from './utils/errors.mts'
+import { CouchPutResponse } from '../schema/couch/couch.output.schema.ts'
+import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
+
+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)
+
+  logger.info(`Deleting document with id: ${id}`)
+  let resp
+  try {
+    resp = await needle('delete', url, null, mergedOpts)
+  } catch (err) {
+    logger.error('Error during delete operation:', err)
+    RetryableError.handleNetworkError(err)
+  }
+
+  if (!resp) {
+    logger.error('No response received from delete request')
+    throw new RetryableError('no response', 503)
+  }
+
+  let result
+  if (typeof resp.body === 'string') {
+    try {
+      result = JSON.parse(resp.body)
+    } catch {
+      result = {}
+    }
+  } else {
+    result = 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)
+  }
+
+  if (resp.statusCode !== 200) {
+    logger.error(`Unexpected status code: ${resp.statusCode}`)
+    throw new Error(result.reason || 'failed')
+  }
+
+  logger.info(`Successfully deleted document: ${id}`)
+  return CouchPutResponse.parse(result)
+}

package/impl/remove.test.mts

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { remove } from './remove.mts'
+import { RetryableError } from './utils/errors.mts'
+import { TEST_DB_URL } from '../test/setup-db.mts'
+
+const baseConfig: CouchConfigInput = {
+  couch: TEST_DB_URL
+}
+
+type DocBody = Record<string, unknown>
+
+async function saveDoc(id: string, body: DocBody) {
+  const response = await needle(
+    'put',
+    `${TEST_DB_URL}/${id}`,
+    {
+      _id: id,
+      ...body
+    },
+    { json: true }
+  )
+
+  if (response.statusCode !== 201 && response.statusCode !== 200) {
+    throw new Error(`Failed to save document ${id}: ${response.statusCode}`)
+  }
+
+  return response.body as { rev: string }
+}
+
+async function getDoc(id: string) {
+  return needle('get', `${TEST_DB_URL}/${id}`, null, { json: true })
+}
+
+suite('remove', () => {
+  test('it should throw if provided config is invalid', async () => {
+    await assert.rejects(async () => {
+      await remove(
+        // @ts-expect-error testing invalid config
+        { couch: DB_URL, useConsoleLogger: true, unexpected: true },
+        'doc-invalid-config',
+        '1-invalid'
+      )
+    })
+  })
+
+  test('integration with pouchdb-server', async t => {
+    await t.test('removes an existing document', async () => {
+      const remove_doc_id = `remove-doc-1-${Date.now()}`
+      const { rev } = await saveDoc(remove_doc_id, { kind: 'test', count: 1 })
+
+      const result = await remove(baseConfig, remove_doc_id, rev)
+      assert.strictEqual(result.ok, true)
+      assert.strictEqual(result.id, remove_doc_id)
+      assert.strictEqual(result.statusCode, 200)
+
+      const { statusCode, body } = await getDoc(remove_doc_id)
+      assert.strictEqual(statusCode, 404)
+      assert.strictEqual(body?.error, 'not_found')
+    })
+
+    await t.test('returns not found metadata when document is missing', async () => {
+      const result = await remove(baseConfig, 'remove-doc-missing', '1-missing')
+      assert.strictEqual(result.ok, false)
+      assert.strictEqual(result.error, 'not_found')
+      assert.strictEqual(result.statusCode, 404)
+    })
+
+    await t.test('propagates retryable network errors', async () => {
+      const offlineConfig: CouchConfigInput = {
+        couch: 'http://localhost:6553/offline-remove-db'
+      }
+
+      await assert.rejects(
+        () => remove(offlineConfig, 'remove-doc-network', '1-offline'),
+        (err: unknown) => err instanceof RetryableError && err.statusCode === 503
+      )
+    })
+  })
+})

package/impl/retry.mts

@@ -0,0 +1,66 @@
+import { setTimeout } from 'node:timers/promises'
+import { RetryableError } from './utils/errors.mts'
+
+/**
+ * Settings that control how retry attempts are scheduled.
+ */
+export interface RetryOptions {
+  /**
+   * Maximum number of retry attempts before rethrowing the original error.
+   */
+  maxRetries?: number
+  /**
+   * Initial wait duration in milliseconds before attempting the first retry.
+   */
+  initialDelay?: number
+  /**
+   * Multiplier applied to the delay after each retry to implement exponential backoff.
+   */
+  backoffFactor?: number
+  /**
+   * Upper bound, in milliseconds, for the delay between retries.
+   */
+  maxDelay?: number
+}
+
+type MaybePromise<T> = PromiseLike<T> | T
+
+/**
+ * Wrap an async-capable function with retry semantics that respect {@link RetryableError}.
+ * @typeParam Fn - The function signature to decorate with retry handling.
+ * @param fn The function to invoke with retry support.
+ * @param options Retry tuning parameters.
+ * @returns A function mirroring `fn` that automatically retries on {@link RetryableError}.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function withRetry<Fn extends (...args: any[]) => MaybePromise<any>>(
+  fn: Fn,
+  options: RetryOptions = {}
+): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
+  const { maxRetries = 3, initialDelay = 1000, backoffFactor = 2, maxDelay = 30000 } = options
+
+  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+    let delay = initialDelay
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const result = await fn(...args)
+        return result
+      } catch (error) {
+        if (!(error instanceof RetryableError)) {
+          throw error
+        }
+
+        if (attempt === maxRetries) {
+          throw error
+        }
+
+        const nextDelay = Math.min(delay, maxDelay)
+        await setTimeout(nextDelay)
+        delay *= backoffFactor
+      }
+    }
+
+    throw new RetryableError('withRetry exhausted retry attempts without resolving the operation')
+  }
+}

package/impl/retry.test.mts

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { withRetry } from './retry.mts'
+import { RetryableError } from './utils/errors.mts'
+
+suite('withRetry', () => {
+  test('resolves when the wrapped function succeeds without retries', async () => {
+    let count = 0
+    const fn = async (value: string) => {
+      count += 1
+      return value
+    }
+
+    const wrapped = withRetry(fn)
+    const result = await wrapped('ok')
+
+    assert.strictEqual(result, 'ok')
+    assert.strictEqual(count, 1)
+  })
+
+  test('retries on RetryableError until success', async () => {
+    let attempts = 0
+    const fn = async () => {
+      attempts += 1
+      if (attempts < 3) {
+        throw new RetryableError('temporary', 503)
+      }
+      return 'done'
+    }
+
+    const wrapped = withRetry(fn, { initialDelay: 0, maxDelay: 0 })
+    const result = await wrapped()
+
+    assert.strictEqual(result, 'done')
+    assert.strictEqual(attempts, 3)
+  })
+
+  test('propagates non retryable errors immediately', async () => {
+    let attempts = 0
+    const fn = async () => {
+      attempts += 1
+      throw new Error('fatal')
+    }
+
+    const wrapped = withRetry(fn, { initialDelay: 0, maxDelay: 0 })
+
+    await assert.rejects(
+      () => wrapped(),
+      (err: unknown) => {
+        return err instanceof Error && !(err instanceof RetryableError) && err.message === 'fatal'
+      }
+    )
+    assert.strictEqual(attempts, 1)
+  })
+
+  test('throws after exceeding the maximum retries', async () => {
+    let attempts = 0
+    const fn = async () => {
+      attempts += 1
+      throw new RetryableError('still failing', 503)
+    }
+
+    const wrapped = withRetry(fn, {
+      maxRetries: 2,
+      initialDelay: 0,
+      maxDelay: 0
+    })
+
+    await assert.rejects(
+      () => wrapped(),
+      (err: unknown) => {
+        return err instanceof RetryableError && err.message === 'still failing'
+      }
+    )
+    assert.strictEqual(attempts, 3)
+  })
+})