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

package/impl/patch.mts

@@ -0,0 +1,134 @@
+import { put } from './put.mts'
+import { get } from './get.mts'
+import { createLogger } from './utils/logger.mts'
+import { setTimeout } from 'node:timers/promises'
+import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
+import { z } from 'zod'
+
+const PatchProperties = z
+  .looseObject({
+    _rev: z.string('_rev is required for patch operations')
+  })
+  .describe('Patch payload with _rev')
+
+/**
+ * Patch a CouchDB document by merging provided properties.
+ * Validates that the _rev matches before applying the patch.
+ *
+ * @param configInput - CouchDB configuration
+ * @param id - Document ID to patch
+ * @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
+ */
+export const patch = async (
+  configInput: CouchConfigInput,
+  id: string,
+  _properties: z.infer<typeof PatchProperties>
+) => {
+  const config = CouchConfig.parse(configInput)
+  const properties = PatchProperties.parse(_properties)
+  const logger = createLogger(configInput)
+
+  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 updatedDoc = { ...doc, ...properties }
+  logger.debug('Merged document:', updatedDoc)
+  const result = await put(config, updatedDoc)
+  logger.info(`Successfully patched document ${id}, rev: ${result.rev}`)
+  return result
+}
+
+/**
+ * Patch a CouchDB document by merging provided properties.
+ * This function will retry on conflicts using an exponential backoff strategy.
+ *
+ * @remarks patchDangerously can clobber data. It will retry even if a conflict happens. There are some use cases for this, but you have been warned, hence the name.
+ *
+ * @param configInput - CouchDB configuration
+ * @param id - Document ID to patch
+ * @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
+ */
+export const patchDangerously = async (
+  configInput: CouchConfigInput,
+  id: string,
+  properties: Record<string, unknown>
+) => {
+  const config = CouchConfig.parse(configInput)
+  const logger = createLogger(config)
+  const maxRetries = config.maxRetries || 5
+  let delay = config.initialDelay || 1000
+  let attempts = 0
+
+  logger.info(`Starting patch operation for document ${id}`)
+  logger.debug('Patch properties:', properties)
+
+  while (attempts <= maxRetries) {
+    logger.debug(`Attempt ${attempts + 1} of ${maxRetries + 1}`)
+    try {
+      const doc = await get(config, id)
+      if (!doc) {
+        logger.warn(`Document ${id} not found`)
+        return { ok: false, statusCode: 404, error: 'not_found' }
+      }
+
+      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.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' }
+      }
+
+      // Handle other errors (network, etc)
+      attempts++
+      if (attempts > maxRetries) {
+        const error = `Failed to patch after ${maxRetries} attempts: ${err}`
+        logger.error(error)
+        return { ok: false, statusCode: 500, error }
+      }
+
+      logger.warn(`Error during patch attempt ${attempts}: ${err}`)
+      await setTimeout(delay)
+      logger.debug(`Retrying after ${delay}ms`)
+    }
+  }
+}

package/impl/patch.test.mts

@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { get } from './get.mts'
+import { patch, patchDangerously } from './patch.mts'
+import { TEST_DB_URL } from '../test/setup-db.mts'
+
+const baseConfig: CouchConfigInput = {
+  couch: TEST_DB_URL,
+  initialDelay: 10,
+  maxRetries: 2,
+  backoffFactor: 1.2
+}
+
+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 }
+}
+
+suite('patch', () => {
+  test('it will throw if provided config is invalid', async () => {
+    await assert.rejects(async () => {
+      // @ts-expect-error testing invalid config
+      await patch({ notAnOption: true, couch: DB_URL, useConsoleLogger: true }, 'doc1', {
+        foo: 'bar'
+      })
+    })
+
+    await assert.rejects(async () => {
+      await patchDangerously(
+        // @ts-expect-error testing invalid config
+        { anotherBadOption: 123, couch: DB_URL, useConsoleLogger: true },
+        'doc1',
+        { foo: 'bar' }
+      )
+    })
+  })
+
+  test('patch should throw if document revision is not provided', async () => {
+    await assert.rejects(
+      async () => {
+        // @ts-expect-error testing missing _rev
+        await patch(baseConfig, 'doc-no-rev', { foo: 'bar' })
+      },
+      {
+        message: /_rev is required for patch operations/
+      }
+    )
+  })
+
+  test('integration with pouchdb-server', async t => {
+    const patch_doc_id = `patch-doc-${Date.now()}`
+    const initial = await saveDoc(patch_doc_id, { message: 'original' })
+
+    await t.test('patch updates document when revision matches', async () => {
+      const result = await patch(baseConfig, patch_doc_id, {
+        _rev: initial.rev,
+        message: 'patched',
+        updated: true
+      })
+      assert.ok(result.ok)
+      assert.ok(result.rev)
+
+      const doc = await get(baseConfig, patch_doc_id)
+      assert.strictEqual(doc?.message, 'patched')
+      assert.strictEqual(doc?.updated, true)
+    })
+
+    await t.test('patch returns conflict on stale revision', async () => {
+      const current = await get(baseConfig, patch_doc_id)
+      const staleRev = initial.rev
+
+      const conflict = await patch(baseConfig, patch_doc_id, {
+        _rev: staleRev,
+        message: 'should-fail'
+      })
+      assert.strictEqual(conflict.ok, false)
+      assert.strictEqual(conflict.statusCode, 409)
+      assert.strictEqual(conflict.error, 'conflict')
+
+      const doc = await get(baseConfig, patch_doc_id)
+      assert.strictEqual(doc?.message, current?.message)
+    })
+
+    await t.test('patchDangerously merges properties without revision', async () => {
+      const result = await patchDangerously(baseConfig, patch_doc_id, {
+        description: 'dangerously updated'
+      })
+      assert.ok(result?.ok)
+
+      const doc = await get(baseConfig, patch_doc_id)
+      assert.strictEqual(doc?.description, 'dangerously updated')
+    })
+
+    await t.test('patchDangerously returns not_found when document missing', async () => {
+      const response = await patchDangerously(baseConfig, 'missing-doc', {
+        message: 'noop'
+      })
+      assert.strictEqual(response?.ok, false)
+      assert.strictEqual(response?.statusCode, 404)
+      assert.strictEqual(response?.error, 'not_found')
+    })
+
+    await t.test('patchDangerously reports failure after exhausting retries', async () => {
+      const doc = await get(baseConfig, patch_doc_id)
+      const conflictConfig: CouchConfigInput = {
+        ...baseConfig,
+        maxRetries: 1,
+        initialDelay: 1,
+        backoffFactor: 1
+      }
+
+      const response = await patchDangerously(conflictConfig, patch_doc_id, {
+        _rev: initial.rev,
+        conflicted: true
+      })
+      assert.strictEqual(response?.ok, false)
+      assert.strictEqual(response?.statusCode, 500)
+      assert.match(response?.error ?? '', /Failed to patch after 1 attempts/)
+
+      const current = await get(baseConfig, patch_doc_id)
+      assert.strictEqual(current?.conflicted, undefined)
+      assert.strictEqual(current?._rev, doc?._rev)
+    })
+  })
+})

package/impl/put.mts

@@ -0,0 +1,56 @@
+import needle from 'needle'
+import { createLogger } from './utils/logger.mts'
+import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
+import { RetryableError } 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'
+
+export const put = async (
+  configInput: CouchConfigInput,
+  doc: CouchDoc
+): Promise<z.infer<typeof CouchPutResponse>> => {
+  const config = CouchConfig.parse(configInput)
+  const logger = createLogger(config)
+  const url = `${config.couch}/${doc._id}`
+  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)
+  } catch (err) {
+    logger.error('Error during put operation:', err)
+    RetryableError.handleNetworkError(err)
+  }
+
+  if (!resp) {
+    logger.error('No response received from put request')
+    throw new RetryableError('no response', 503)
+  }
+
+  const result = 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)
+  }
+
+  if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
+    logger.warn(`Retryable status code received: ${resp.statusCode}`)
+    throw new RetryableError(result.reason || 'retryable error', resp.statusCode)
+  }
+
+  logger.info(`Successfully saved document: ${doc._id}`)
+  return CouchPutResponse.parse(result)
+}

package/impl/put.test.mts

@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { put } from './put.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 getDoc(id: string) {
+  return needle('get', `${TEST_DB_URL}/${id}`, null, { json: true })
+}
+
+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 }
+}
+
+suite('put', () => {
+  test('rejects invalid config arguments', async () => {
+    await assert.rejects(async () => {
+      // @ts-expect-error testing invalid config
+      await put({ couch: DB_URL, unsupported: true }, { _id: 'bad-config-doc' })
+    })
+  })
+
+  test('propagates retryable network failures', async () => {
+    const offlineConfig: CouchConfigInput = {
+      couch: 'http://localhost:6555/offline-put-test'
+    }
+
+    await assert.rejects(
+      () => put(offlineConfig, { _id: 'offline-doc', kind: 'offline' }),
+      (err: unknown) => err instanceof RetryableError && err.statusCode === 503
+    )
+  })
+
+  test('integration with pouchdb-server', async t => {
+    let initialRev: string | undefined
+    const put_doc_id = `put-doc-${Date.now()}`
+
+    await t.test('creates documents via PUT', async () => {
+      const result = await put(baseConfig, {
+        _id: put_doc_id,
+        type: 'integration',
+        count: 1
+      })
+      assert.ok(result)
+      assert.strictEqual(result.ok, true)
+      assert.strictEqual(result.id, put_doc_id)
+      assert.strictEqual(result.statusCode, 201)
+      assert.ok(typeof result.rev === 'string')
+      initialRev = result.rev
+
+      const { statusCode, body } = await getDoc(put_doc_id)
+      assert.strictEqual(statusCode, 200)
+      assert.strictEqual(body?.type, 'integration')
+      assert.strictEqual(body?.count, 1)
+    })
+
+    await t.test('updates documents when revision supplied', async () => {
+      if (!initialRev) throw new Error('Expected initial revision to be captured')
+
+      const updateResult = await put(baseConfig, {
+        _id: put_doc_id,
+        _rev: initialRev,
+        type: 'integration',
+        count: 2
+      })
+      assert.ok(updateResult)
+      assert.strictEqual(updateResult.ok, true)
+      assert.strictEqual(updateResult.statusCode, 201)
+      assert.ok(typeof updateResult.rev === 'string')
+
+      const { body } = await getDoc(put_doc_id)
+      assert.strictEqual(body?.count, 2)
+      initialRev = updateResult.rev
+    })
+
+    await t.test('reports conflicts when revision is stale', async () => {
+      if (!initialRev) throw new Error('Expected revision to be captured')
+      const staleRev = initialRev
+      const latest = await saveDoc(put_doc_id, {
+        _rev: staleRev,
+        type: 'integration',
+        count: 3
+      })
+
+      const result = await put(baseConfig, {
+        _id: put_doc_id,
+        _rev: staleRev,
+        type: 'integration',
+        count: 4
+      })
+      assert.ok(result)
+      assert.strictEqual(result.ok, false)
+      assert.strictEqual(result.error, 'conflict')
+      assert.strictEqual(result.statusCode, 409)
+
+      const { body } = await getDoc(put_doc_id)
+      assert.strictEqual(body?.count, 3)
+      initialRev = latest.rev
+    })
+  })
+})

package/impl/query.mts

@@ -0,0 +1,224 @@
+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 { 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'
+
+export async function query<
+  DocSchema extends StandardSchemaV1 = typeof CouchDoc,
+  KeySchema extends StandardSchemaV1 = ZodAny,
+  ValueSchema extends StandardSchemaV1 = ZodAny
+>(
+  config: CouchConfigInput,
+  view: ViewString,
+  options: ViewOptions & {
+    include_docs: true
+    validate?: {
+      onInvalidDoc?: OnInvalidDocAction
+      docSchema?: DocSchema
+      keySchema?: KeySchema
+      valueSchema?: ValueSchema
+    }
+  }
+): Promise<ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>>
+
+export async function query<
+  DocSchema extends StandardSchemaV1 = ZodNever,
+  KeySchema extends StandardSchemaV1 = ZodAny,
+  ValueSchema extends StandardSchemaV1 = ZodAny
+>(
+  config: CouchConfigInput,
+  view: ViewString,
+  options: ViewOptions & {
+    include_docs?: false | undefined
+    validate?: {
+      onInvalidDoc?: OnInvalidDocAction
+      docSchema?: DocSchema
+      keySchema?: KeySchema
+      valueSchema?: ValueSchema
+    }
+  }
+): Promise<ViewQueryResponseValidated<ZodNever, KeySchema, ValueSchema>>
+
+export async function query(
+  config: CouchConfigInput,
+  view: ViewString,
+  options?: ViewOptions
+): Promise<ViewQueryResponseValidated<ZodNever, ZodAny, ZodAny>>
+
+/**
+ * Executes a CouchDB view query with optional schema validation and automatic handling
+ * of HTTP method selection, query string construction, and retryable errors.
+ *
+ * @remarks
+ * When using the validation feature, each row in the response will be validated against the provided
+ * Types will be inferred from the StandardSchemaV1 supplied in the `options.validate` object.
+ *
+ * @template DocSchema - StandardSchemaV1 used to validate each returned `doc`, if provided.
+ * @template KeySchema - StandardSchemaV1 used to validate each row `key`, if provided.
+ * @template ValueSchema - StandardSchemaV1 used to validate each row `value`, if provided.
+ *
+ * @param _config - CouchDB configuration data that is validated before use.
+ * @param view - Fully qualified design document and view identifier (e.g., `_design/foo/_view/bar`).
+ * @param options - CouchDB view options, including optional validation schemas.
+ *
+ * @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.
+ */
+export async function query<
+  DocSchema extends StandardSchemaV1,
+  KeySchema extends StandardSchemaV1,
+  ValueSchema extends StandardSchemaV1
+>(
+  _config: CouchConfigInput,
+  view: ViewString,
+  options: ViewOptions & {
+    validate?: {
+      onInvalidDoc?: OnInvalidDocAction
+      docSchema?: DocSchema
+      keySchema?: KeySchema
+      valueSchema?: ValueSchema
+    }
+  } = {}
+): Promise<ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>> {
+  const configParseResult = CouchConfig.safeParse(_config)
+  const logger = createLogger(_config)
+  logger.info(`Starting view query: ${view}`)
+  logger.debug('Query options:', ViewOptions.parse(options || {}))
+  if (!configParseResult.success) {
+    logger.error(`Invalid configuration provided: ${z.prettifyError(configParseResult.error)}`)
+    throw configParseResult.error
+  }
+
+  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)
+
+  // 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') {
+    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 keysAsString = `keys=${JSON.stringify(options.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'
+      if (qs.length > 0) qs += '&'
+      else qs = ''
+      qs += keysAsString
+    } else {
+      method = 'post'
+      payload = { keys: options.keys }
+    }
+  }
+
+  logger.debug('Generated query string:', qs)
+  const url = `${config.couch}/${view}?${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)
+  } catch (err) {
+    logger.error('Network error during query:', err)
+    RetryableError.handleNetworkError(err)
+  }
+
+  if (!results) {
+    logger.error('No response received from query request')
+    throw new RetryableError('no response', 503)
+  }
+
+  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 (body.error) {
+    logger.error(`Query error: ${JSON.stringify(body)}`)
+    throw new Error(`CouchDB query error: ${body.error} - ${body.reason || ''}`)
+  }
+
+  // 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)
+  }
+
+  logger.info(`Successfully executed view query: ${view}`)
+  logger.debug('Query response:', body)
+
+  return body
+}
+
+export type QueryBound = {
+  <
+    DocSchema extends StandardSchemaV1 = typeof CouchDoc,
+    KeySchema extends StandardSchemaV1 = ZodAny,
+    ValueSchema extends StandardSchemaV1 = ZodAny
+  >(
+    view: ViewString,
+    options: ViewOptions & {
+      include_docs: true
+      validate?: {
+        onInvalidDoc?: OnInvalidDocAction
+        docSchema?: DocSchema
+        keySchema?: KeySchema
+        valueSchema?: ValueSchema
+      }
+    }
+  ): Promise<ViewQueryResponseValidated<DocSchema, KeySchema, ValueSchema>>
+  <
+    DocSchema extends StandardSchemaV1 = ZodNever,
+    KeySchema extends StandardSchemaV1 = ZodAny,
+    ValueSchema extends StandardSchemaV1 = ZodAny
+  >(
+    view: ViewString,
+    options: ViewOptions & {
+      include_docs?: false | undefined
+      validate?: {
+        onInvalidDoc?: OnInvalidDocAction
+        docSchema?: DocSchema
+        keySchema?: KeySchema
+        valueSchema?: ValueSchema
+      }
+    }
+  ): Promise<ViewQueryResponseValidated<ZodNever, KeySchema, ValueSchema>>
+  (
+    view: ViewString,
+    options?: ViewOptions
+  ): Promise<ViewQueryResponseValidated<ZodNever, ZodAny, ZodAny>>
+}