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

package/impl/bulkSave.test.mts

@@ -0,0 +1,319 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { bulkSave, bulkSaveTransaction } from './bulkSave.mts'
+import { RetryableError } from './utils/errors.mts'
+import {
+  TransactionRollbackError,
+  TransactionVersionConflictError
+} from './utils/transactionErrors.mts'
+import { TEST_DB_URL } from '../test/setup-db.mts'
+
+const baseConfig: CouchConfigInput = {
+  couch: TEST_DB_URL,
+  useConsoleLogger: true
+}
+
+const transactionBaseConfig: CouchConfigInput = {
+  couch: TEST_DB_URL,
+  bindWithRetry: false,
+  useConsoleLogger: true
+}
+
+type EventRecord = { event: string; payload: unknown }
+
+function createTestEmitter() {
+  const events: EventRecord[] = []
+  const handlers = new Map<string, Array<(payload: unknown) => Promise<void> | void>>()
+
+  return {
+    events,
+    on(event: string, handler: (payload: unknown) => Promise<void> | void) {
+      const list = handlers.get(event) ?? []
+      list.push(handler)
+      handlers.set(event, list)
+    },
+    async emit(event: string, payload: unknown) {
+      events.push({ event, payload })
+      const list = handlers.get(event)
+      if (!list) return
+      for (const handler of list) {
+        await handler(payload)
+      }
+    }
+  }
+}
+
+async function saveDoc(dbUrl: string, id: string, body: Record<string, unknown>) {
+  const response = await needle('put', `${dbUrl}/${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 getDocFrom(dbUrl: string, id: string) {
+  return needle('get', `${dbUrl}/${id}`, null, { json: true })
+}
+
+async function getDoc(id: string) {
+  return getDocFrom(TEST_DB_URL, id)
+}
+
+suite('bulkSave', () => {
+  test('rejects invalid config arguments', async () => {
+    await assert.rejects(async () => {
+      // @ts-expect-error intentionally passing unsupported option
+      await bulkSave({ couch: TEST_DB_URL, unsupported: true }, [
+        { _id: 'bad-config-doc', count: 1 }
+      ])
+    })
+  })
+
+  test('throws error if called with no docs', async () => {
+    await assert.rejects(async () => {
+      // @ts-expect-error testing no docs
+      await bulkSave(baseConfig, null)
+    })
+    await assert.rejects(async () => {
+      await bulkSave(baseConfig, [])
+    })
+  })
+
+  test('propagates retryable network failures', async () => {
+    const offlineConfig: CouchConfigInput = {
+      couch: 'http://localhost:6554/offline-bulk-save'
+    }
+
+    await assert.rejects(
+      () => bulkSave(offlineConfig, [{ _id: 'offline-doc', count: 1 }]),
+      (err: unknown) => err instanceof RetryableError && err.statusCode === 503
+    )
+  })
+
+  test('integration with pouchdb-server', async t => {
+    let docTwoInitialRev: string | undefined
+    const docs = [
+      { _id: `bulk-save-doc-1-${Date.now()}`, type: 'integration', count: 1 },
+      { _id: `bulk-save-doc-2-${Date.now()}`, type: 'integration', count: 2 }
+    ]
+
+    await t.test('creates documents via _bulk_docs', async () => {
+      const results = await bulkSave(baseConfig, docs)
+      assert.strictEqual(results.length, 2)
+      const [first, second] = results
+      assert.ok(first)
+      assert.strictEqual(first.id, docs[0]._id)
+      assert.strictEqual(first.ok, true)
+      assert.ok(second)
+      assert.strictEqual(second.id, docs[1]._id)
+      assert.strictEqual(second.ok, true)
+
+      docTwoInitialRev = second.rev ?? undefined
+      assert.ok(typeof docTwoInitialRev === 'string')
+
+      const { statusCode, body } = await getDoc(docs[0]._id)
+      assert.strictEqual(statusCode, 200)
+      assert.strictEqual(body?.type, 'integration')
+      assert.strictEqual(body?.count, 1)
+    })
+
+    await t.test('updates documents when revision supplied', async () => {
+      const current = await getDoc(docs[1]._id)
+      assert.strictEqual(current.statusCode, 200)
+      const updateResults = await bulkSave(baseConfig, [
+        {
+          _id: docs[1]._id,
+          _rev: current.body?._rev,
+          type: 'integration',
+          count: 3
+        }
+      ])
+
+      assert.strictEqual(updateResults.length, 1)
+      const [updated] = updateResults
+      assert.ok(updated)
+      assert.strictEqual(updated.ok, true)
+      assert.ok(updated.rev)
+
+      const { body } = await getDoc(docs[1]._id)
+      assert.strictEqual(body?.count, 3)
+    })
+
+    await t.test('reports conflicts when revision is stale', async () => {
+      if (!docTwoInitialRev) throw new Error('Expected initial revision to be captured')
+
+      const conflictResults = await bulkSave(baseConfig, [
+        {
+          _id: docs[1]._id,
+          _rev: docTwoInitialRev,
+          type: 'integration',
+          count: 99
+        }
+      ])
+
+      assert.strictEqual(conflictResults.length, 1)
+      const [conflict] = conflictResults
+      assert.ok(conflict)
+      assert.strictEqual(conflict.id, docs[1]._id)
+      assert.strictEqual(conflict.error, 'conflict')
+      assert.ok(conflict.reason)
+    })
+  })
+})
+
+suite('bulkSaveTransaction', () => {
+  test('integration with pouchdb-server', async t => {
+    await t.test('completes transaction for new and existing docs', async () => {
+      const emitter = createTestEmitter()
+      const config: CouchConfigInput = {
+        ...transactionBaseConfig,
+        '~emitter': emitter
+      }
+
+      const existingId = `txn-existing-success-${Date.now()}`
+      const newId = `txn-new-success-${Date.now()}`
+      const transactionId = `bulk-transaction-success-${Date.now()}`
+
+      const existing = await saveDoc(TEST_DB_URL, existingId, {
+        type: 'transaction',
+        count: 1
+      })
+
+      const docs = [
+        {
+          _id: existingId,
+          _rev: existing.rev,
+          type: 'transaction',
+          count: 2
+        },
+        { _id: newId, type: 'transaction', count: 1 }
+      ]
+
+      const results = await bulkSaveTransaction(config, transactionId, docs)
+      assert.strictEqual(results.length, 2)
+      assert.ok(results[0]?.ok)
+      assert.strictEqual(results[0]?.id, existingId)
+      assert.ok(results[1]?.ok)
+      assert.strictEqual(results[1]?.id, newId)
+
+      const updatedExisting = await getDocFrom(TEST_DB_URL, existingId)
+      assert.strictEqual(updatedExisting.statusCode, 200)
+      assert.strictEqual(updatedExisting.body?.count, 2)
+
+      const createdDoc = await getDocFrom(TEST_DB_URL, newId)
+      assert.strictEqual(createdDoc.statusCode, 200)
+      assert.strictEqual(createdDoc.body?.count, 1)
+
+      const transactionDoc = await getDocFrom(TEST_DB_URL, `txn:${transactionId}`)
+      assert.strictEqual(transactionDoc.statusCode, 200)
+      assert.strictEqual(transactionDoc.body?.status, 'completed')
+
+      assert.ok(emitter.events.some(({ event }) => event === 'transaction-created'))
+      assert.ok(emitter.events.some(({ event }) => event === 'transaction-completed'))
+    })
+
+    await t.test('throws TransactionVersionConflictError when revisions mismatch', async () => {
+      const emitter = createTestEmitter()
+      const config: CouchConfigInput = {
+        ...transactionBaseConfig,
+        '~emitter': emitter
+      }
+
+      const docId = `txn-conflict-doc-${Date.now()}`
+      const transactionId = `bulk-transaction-conflict-${Date.now()}`
+
+      const first = await saveDoc(TEST_DB_URL, docId, {
+        type: 'conflict',
+        count: 1
+      })
+      await saveDoc(TEST_DB_URL, docId, {
+        _rev: first.rev,
+        type: 'conflict',
+        count: 2
+      })
+      await assert.rejects(
+        () =>
+          bulkSaveTransaction(config, transactionId, [
+            {
+              _id: docId,
+              _rev: first.rev,
+              type: 'conflict',
+              count: 3
+            }
+          ]),
+        (err: unknown) =>
+          err instanceof TransactionVersionConflictError && err.conflictingIds.includes(docId)
+      )
+
+      assert.ok(emitter.events.some(({ event }) => event === 'transaction-created'))
+      assert.ok(emitter.events.some(({ event }) => event === 'transaction-revs-fetched'))
+    })
+
+    await t.test('rolls back changes when bulk save fails', async () => {
+      const emitter = createTestEmitter()
+      const config: CouchConfigInput = {
+        ...transactionBaseConfig,
+        '~emitter': emitter
+      }
+
+      const successId = `txn-rollback-existing-${Date.now()}`
+      const conflictId = `txn-rollback-conflict-${Date.now()}`
+      const transactionId = `bulk-transaction-rollback-${Date.now()}`
+
+      const existing = await saveDoc(TEST_DB_URL, successId, {
+        type: 'rollback',
+        count: 1
+      })
+      const conflicting = await saveDoc(TEST_DB_URL, conflictId, {
+        type: 'rollback',
+        count: 1
+      })
+
+      emitter.on('transaction-revs-checked', async () => {
+        await needle(
+          'put',
+          `${TEST_DB_URL}/${conflictId}`,
+          {
+            _id: conflictId,
+            _rev: conflicting.rev,
+            type: 'rollback',
+            count: 99
+          },
+          { json: true }
+        )
+      })
+
+      await assert.rejects(
+        () =>
+          bulkSaveTransaction(config, transactionId, [
+            { _id: successId, _rev: existing.rev, type: 'rollback', count: 2 },
+            {
+              _id: conflictId,
+              _rev: conflicting.rev,
+              type: 'rollback',
+              count: 2
+            }
+          ]),
+        (err: unknown) => err instanceof TransactionRollbackError
+      )
+
+      const rolledBack = await getDocFrom(TEST_DB_URL, successId)
+      assert.strictEqual(rolledBack.statusCode, 200)
+      assert.strictEqual(rolledBack.body?.count, 1)
+
+      const conflicted = await getDocFrom(TEST_DB_URL, conflictId)
+      assert.strictEqual(conflicted.statusCode, 200)
+      assert.strictEqual(conflicted.body?.count, 99)
+
+      const transactionDoc = await getDocFrom(TEST_DB_URL, `txn:${transactionId}`)
+      assert.strictEqual(transactionDoc.statusCode, 200)
+      assert.strictEqual(transactionDoc.body?.status, 'rolled_back')
+
+      assert.ok(emitter.events.some(({ event }) => event === 'transaction-rolled-back'))
+    })
+  })
+})

package/impl/get.mts

@@ -0,0 +1,137 @@
+import needle from 'needle'
+import { z } from 'zod'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { createLogger } from './utils/logger.mts'
+import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
+import { RetryableError, NotFoundError } from './utils/errors.mts'
+import type { StandardSchemaV1 } from '../types/standard-schema.ts'
+import { CouchDoc } from '../schema/couch/couch.output.schema.ts'
+
+export type GetOptions<DocSchema extends StandardSchemaV1> = {
+  validate?: {
+    docSchema?: DocSchema
+  }
+}
+
+type InternalGetOptions<DocSchema extends StandardSchemaV1> = GetOptions<DocSchema> & {
+  rev?: string
+}
+
+const ValidSchema = z.custom(
+  value => {
+    return value !== null && typeof value === 'object' && '~standard' in value
+  },
+  {
+    message: 'docSchema must be a valid StandardSchemaV1 schema'
+  }
+)
+
+export const CouchGetOptions = z.object({
+  rev: z.string().optional().describe('the couch doc revision'),
+  validate: z
+    .object({
+      docSchema: ValidSchema.optional()
+    })
+    .optional()
+    .describe('optional document validation rules')
+})
+
+async function _getWithOptions<DocSchema extends StandardSchemaV1>(
+  config: CouchConfigInput,
+  id: string,
+  options: InternalGetOptions<DocSchema>
+): Promise<StandardSchemaV1.InferOutput<DocSchema> | null> {
+  const parsedOptions = CouchGetOptions.parse({
+    rev: options.rev,
+    validate: options.validate
+  })
+
+  const logger = createLogger(config)
+  const rev = parsedOptions.rev
+  const path = rev ? `${id}?rev=${rev}` : id
+  const url = `${config.couch}/${path}`
+
+  const httpOptions = {
+    json: true,
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  }
+
+  const requestOptions = mergeNeedleOpts(config, httpOptions)
+  logger.info(`Getting document with id: ${id}, rev ${rev ?? 'latest'}`)
+
+  try {
+    const resp = await needle('get', url, null, requestOptions)
+    if (!resp) {
+      logger.error('No response received from get request')
+      throw new RetryableError('no response', 503)
+    }
+
+    const body = resp.body ?? null
+
+    if (resp.statusCode === 404) {
+      if (config.throwOnGetNotFound) {
+        const reason = typeof body?.reason === 'string' ? body.reason : 'not_found'
+        logger.warn(`Document not found (throwing error): ${id}, rev ${rev ?? 'latest'}`)
+        throw new NotFoundError(id, reason)
+      }
+
+      logger.debug(`Document not found (returning undefined): ${id}, rev ${rev ?? 'latest'}`)
+      return null
+    }
+
+    if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
+      const reason = typeof body?.reason === 'string' ? body.reason : 'retryable error'
+      logger.warn(`Retryable status code received: ${resp.statusCode}`)
+      throw new RetryableError(reason, resp.statusCode)
+    }
+
+    if (resp.statusCode !== 200) {
+      const reason = typeof body?.reason === 'string' ? body.reason : 'failed'
+      logger.error(`Unexpected status code: ${resp.statusCode}`)
+      throw new Error(reason)
+    }
+
+    const docSchema = (parsedOptions.validate?.docSchema ?? CouchDoc) as DocSchema
+    const typedDoc = await docSchema['~standard'].validate(body)
+
+    if (typedDoc.issues) {
+      throw typedDoc.issues
+    }
+
+    logger.info(`Successfully retrieved document: ${id}, rev ${rev ?? 'latest'}`)
+    return typedDoc.value
+  } catch (err) {
+    logger.error('Error during get operation:', err)
+    RetryableError.handleNetworkError(err)
+  }
+}
+
+export async function get<DocSchema extends StandardSchemaV1 = typeof CouchDoc>(
+  config: CouchConfigInput,
+  id: string,
+  options?: GetOptions<DocSchema>
+): Promise<StandardSchemaV1.InferOutput<DocSchema> | null> {
+  return _getWithOptions<DocSchema>(config, id, options ?? {})
+}
+
+export type GetBound = <DocSchema extends StandardSchemaV1 = typeof CouchDoc>(
+  id: string,
+  options?: GetOptions<DocSchema>
+) => Promise<StandardSchemaV1.InferOutput<DocSchema> | null>
+
+export async function getAtRev<DocSchema extends StandardSchemaV1>(
+  config: CouchConfigInput,
+  id: string,
+  rev: string,
+  options?: GetOptions<DocSchema>
+): Promise<StandardSchemaV1.InferOutput<DocSchema> | null> {
+  return _getWithOptions<DocSchema>(config, id, { ...options, rev })
+}
+
+export type GetAtRevBound = <DocSchema extends StandardSchemaV1 = typeof CouchDoc>(
+  id: string,
+  rev: string,
+  options?: GetOptions<DocSchema> | undefined
+) => Promise<StandardSchemaV1.InferOutput<DocSchema> | null>

package/impl/get.test.mts

@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import { z } from 'zod'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { get, getAtRev } from './get.mts'
+import { NotFoundError, 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 }
+}
+
+suite('get', () => {
+  test('integration with pouchdb-server', async t => {
+    const doc_valid_id = `doc-valid-${Date.now()}`
+    const doc_invalid_id = `doc-invalid-${Date.now()}`
+    const doc_rev_id = `doc-rev-${Date.now()}`
+    await saveDoc(doc_valid_id, { kind: 'example', count: 7 })
+    await saveDoc(doc_invalid_id, { kind: 'example', count: 'oops' })
+    const firstRev = await saveDoc(doc_rev_id, { version: 1 })
+    await saveDoc(doc_rev_id, { _rev: firstRev.rev, version: 2 })
+
+    await t.test('returns documents and validates schema', async () => {
+      const schema = z.looseObject({
+        _id: z.string(),
+        kind: z.literal('example'),
+        count: z.number()
+      })
+
+      const doc = await get(baseConfig, doc_valid_id, {
+        validate: { docSchema: schema }
+      })
+      assert.ok(doc)
+      assert.strictEqual(doc?.kind, 'example')
+      assert.strictEqual(doc?.count, 7)
+
+      await assert.rejects(
+        () => get(baseConfig, doc_invalid_id, { validate: { docSchema: schema } }),
+        (err: unknown) => {
+          return (
+            Array.isArray(err) &&
+            err[0].message === 'Invalid input: expected number, received string'
+          )
+        }
+      )
+    })
+
+    await t.test('returns null when not found by default', async () => {
+      const missing = await get(baseConfig, 'doc-missing')
+      assert.strictEqual(missing, null)
+    })
+
+    await t.test('throws NotFoundError when configured', async () => {
+      const strictConfig: CouchConfigInput = {
+        ...baseConfig,
+        throwOnGetNotFound: true
+      }
+
+      await assert.rejects(
+        () => get(strictConfig, 'doc-missing'),
+        (err: unknown) => err instanceof NotFoundError && err.docId === 'doc-missing'
+      )
+    })
+
+    await t.test('getAtRev returns specific revision', async () => {
+      const versionedSchema = z.looseObject({
+        _id: z.string(),
+        version: z.number()
+      })
+
+      const latest = await get(baseConfig, doc_rev_id, {
+        validate: { docSchema: versionedSchema }
+      })
+      assert.strictEqual(latest?.version, 2)
+
+      const early = await getAtRev(baseConfig, doc_rev_id, firstRev.rev, {
+        validate: { docSchema: versionedSchema }
+      })
+      assert.strictEqual(early?.version, 1)
+    })
+
+    await t.test('propagates retryable network errors', async () => {
+      const offlineConfig: CouchConfigInput = {
+        couch: 'http://localhost:6553/offline-db'
+      }
+
+      await assert.rejects(
+        () => get(offlineConfig, 'doc-valid'),
+        (err: unknown) => err instanceof RetryableError && err.statusCode === 503
+      )
+    })
+  })
+})

package/impl/getDBInfo.mts

@@ -0,0 +1,67 @@
+import needle, { type NeedleResponse } from 'needle'
+import { RetryableError } from './utils/errors.mts'
+import { createLogger } from './utils/logger.mts'
+import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
+import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
+import { CouchDBInfo } from '../schema/couch/couch.output.schema.ts'
+
+/**
+ * Fetches and returns CouchDB database information.
+ *
+ * @see {@link https://docs.couchdb.org/en/stable/api/database/common.html#get--db | CouchDB API Documentation}
+ *
+ * @param configInput - The CouchDB configuration input.
+ * @returns A promise that resolves to the CouchDB database information.
+ * @throws {RetryableError} `RetryableError` If a retryable error occurs during the request.
+ * @throws {Error} `Error` For other non-retryable errors.
+ *
+ * @example
+ * ```ts
+ * import { getDBInfo } from './impl/getDBInfo.mts';
+ *
+ * const config = { couch: 'http://localhost:5984/my-database' };
+ *
+ * getDBInfo(config)
+ *   .then(info => {
+ *     console.log('Database Info:', info);
+ *   })
+ *   .catch(err => {
+ *     console.error('Error fetching database info:', err);
+ *   });
+ * ```
+ */
+export const getDBInfo = async (configInput: CouchConfigInput) => {
+  const config = CouchConfig.parse(configInput)
+  const logger = createLogger(config)
+  const url = `${config.couch}`
+
+  let resp: NeedleResponse | undefined
+  try {
+    resp = await needle(
+      'get',
+      url,
+      mergeNeedleOpts(config, {
+        json: true,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      })
+    )
+  } catch (err) {
+    logger.error('Error during get operation:', err)
+    RetryableError.handleNetworkError(err)
+  }
+
+  if (!resp) {
+    logger.error('No response received from get request')
+    throw new RetryableError('no response', 503)
+  }
+
+  const result = resp.body
+  if (RetryableError.isRetryableStatusCode(resp.statusCode)) {
+    logger.warn(`Retryable status code received: ${resp.statusCode}`)
+    throw new RetryableError(result.reason ?? 'retryable error', resp.statusCode)
+  }
+
+  return CouchDBInfo.parse(result)
+}

package/impl/getDBInfo.test.mts

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import test, { suite } from 'node:test'
+import type { CouchConfigInput } from '../schema/config.mts'
+import { getDBInfo } from './getDBInfo.mts'
+import { RetryableError } from './utils/errors.mts'
+import { TEST_DB_URL } from '../test/setup-db.mts'
+
+suite('getDBInfo', () => {
+  test('it should throw if provided config is invalid', async () => {
+    await assert.rejects(async () => {
+      await getDBInfo({
+        // @ts-expect-error testing invalid config
+        notAnOption: true,
+        // @ts-expect-error testing invalid config
+        couch: DB_URL,
+        useConsoleLogger: true
+      })
+    })
+  })
+  test('integration with pouchdb-server', async t => {
+    await t.test('returns database metadata', async () => {
+      const config: CouchConfigInput = { couch: TEST_DB_URL }
+      const info = await getDBInfo(config)
+      assert.strictEqual(info.db_name, 'hide-a-bed-test-db')
+      assert.ok(typeof info.doc_count === 'number')
+    })
+  })
+
+  test('throws RetryableError when server marks response retryable', async t => {
+    const port = 8993
+    const server = createServer((_req, res) => {
+      res.statusCode = 503
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify({ reason: 'maintenance' }))
+    })
+
+    await new Promise<void>(resolve => {
+      server.listen(port, resolve)
+    })
+    t.after(() => {
+      server.close()
+    })
+
+    await assert.rejects(
+      () => getDBInfo({ couch: `http://localhost:${port}/retryable` }),
+      (err: unknown) => {
+        assert.ok(err instanceof RetryableError)
+        assert.strictEqual(err.statusCode, 503)
+        assert.strictEqual(err.message, 'maintenance')
+        return true
+      }
+    )
+  })
+
+  test('converts network failures into RetryableError', async () => {
+    await assert.rejects(
+      () => getDBInfo({ couch: 'http://localhost:6555/offline-db' }),
+      (err: unknown) => err instanceof RetryableError && err.statusCode === 503
+    )
+  })
+})