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

package/impl/stream.mts

@@ -0,0 +1,143 @@
+import needle from 'needle'
+import type { IncomingMessage } from 'node:http'
+import Chain from 'stream-chain'
+import Parser from 'stream-json/Parser.js'
+import Pick from 'stream-json/filters/Pick.js'
+import StreamArray from 'stream-json/streamers/StreamArray.js'
+import { CouchConfig, type CouchConfigInput } from '../schema/config.mts'
+import { RetryableError } from './utils/errors.mts'
+import { createLogger } from './utils/logger.mts'
+import { queryString } from './utils/queryString.mts'
+import { mergeNeedleOpts } from './utils/mergeNeedleOpts.mts'
+import type { ViewRow } from '../schema/couch/couch.output.schema.ts'
+import type { ViewOptions } from '../schema/couch/couch.input.schema.ts'
+
+type StreamArrayChunk<Row> = {
+  key: number
+  value: Row
+}
+
+export type OnRow = (row: ViewRow) => void
+type HttpMethod = 'GET' | 'POST'
+
+/**
+ * Execute a CouchDB view query and stream rows as they are received.
+ * @param rawConfig CouchDB configuration
+ * @param view The CouchDB view to query
+ * @param options Query options
+ * @param onRow Callback invoked for each row received
+ */
+export async function queryStream(
+  rawConfig: CouchConfigInput,
+  view: string,
+  options: ViewOptions | undefined,
+  onRow: OnRow
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const config = CouchConfig.parse(rawConfig)
+    const logger = createLogger(config)
+    logger.info(`Starting view query stream: ${view}`)
+    logger.debug('Query options:', options)
+
+    const queryOptions: ViewOptions = options ?? {}
+
+    let method: HttpMethod = 'GET'
+    let payload: Record<string, unknown> | null = null
+    let qs = queryString(queryOptions)
+    logger.debug('Generated query string:', qs)
+
+    if (typeof queryOptions.keys !== 'undefined') {
+      const MAX_URL_LENGTH = 2000
+      const keysAsString = `keys=${encodeURIComponent(JSON.stringify(queryOptions.keys))}`
+
+      if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) {
+        qs += (qs.length > 0 ? '&' : '') + keysAsString
+      } else {
+        method = 'POST'
+        payload = { keys: queryOptions.keys }
+      }
+    }
+
+    const url = `${config.couch}/${view}?${qs}`
+    const opts = {
+      json: true,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      parse_response: false as const
+    }
+    const mergedOpts = mergeNeedleOpts(config, opts)
+
+    const parserPipeline = Chain.chain([
+      new Parser(),
+      new Pick({ filter: 'rows' }),
+      new StreamArray()
+    ])
+
+    let rowCount = 0
+    let settled = false
+
+    const settleReject = (err: Error) => {
+      if (settled) return
+      settled = true
+      reject(err)
+    }
+
+    const settleResolve = () => {
+      if (settled) return
+      settled = true
+      resolve()
+    }
+
+    let request: ReturnType<typeof needle.get> | ReturnType<typeof needle.post> | null = null
+
+    parserPipeline.on('data', (chunk: StreamArrayChunk<ViewRow>) => {
+      try {
+        rowCount++
+        onRow(chunk.value)
+      } catch (callbackErr) {
+        const error = callbackErr instanceof Error ? callbackErr : new Error(String(callbackErr))
+        parserPipeline.destroy(error)
+        settleReject(error)
+      }
+    })
+
+    parserPipeline.on('error', (err: Error) => {
+      logger.error('Stream parsing error:', err)
+      parserPipeline.destroy()
+      settleReject(new Error(`Stream parsing error: ${err.message}`, { cause: err }))
+    })
+
+    parserPipeline.on('end', () => {
+      logger.info(`Stream completed, processed ${rowCount} rows`)
+      settleResolve()
+    })
+
+    request = method === 'GET' ? needle.get(url, mergedOpts) : needle.post(url, payload, mergedOpts)
+
+    request.on('response', (response: IncomingMessage) => {
+      logger.debug(`Received response with status code: ${response.statusCode}`)
+      if (RetryableError.isRetryableStatusCode(response.statusCode)) {
+        logger.warn(`Retryable status code received: ${response.statusCode}`)
+        settleReject(new RetryableError('retryable error during stream query', response.statusCode))
+        // @ts-expect-error bad type?
+        request.destroy()
+      }
+    })
+
+    request.on('error', (err: NodeJS.ErrnoException) => {
+      logger.error('Network error during stream query:', err)
+      parserPipeline.destroy(err)
+      try {
+        RetryableError.handleNetworkError(err)
+      } catch (retryErr) {
+        settleReject(retryErr as Error)
+        return
+      } finally {
+        settleReject(err)
+      }
+    })
+
+    request.pipe(parserPipeline)
+  })
+}

package/impl/stream.test.mts

@@ -0,0 +1,205 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { queryStream } from './stream.mts'
+import { bindConfig } from './bindConfig.mts'
+
+const startServer = async (handler: Parameters<typeof createServer>[0]) => {
+  const server = createServer(handler)
+  await new Promise<void>(resolve => server.listen(0, resolve))
+  return server
+}
+
+suite('queryStream', () => {
+  test('queryStream streams rows from chunked response', async t => {
+    const expectedRows = [
+      { id: 'row-1', key: 'row-1', value: { count: 1 } },
+      { id: 'row-2', key: 'row-2', value: { count: 2 } }
+    ]
+
+    // @ts-expect-error testing server
+    const server = await startServer((req, res) => {
+      res.on('error', () => {})
+      const requestUrl = new URL(req.url ?? '/', `http://${req.headers.host}`)
+      assert.strictEqual(req.method, 'GET')
+      assert.strictEqual(requestUrl.pathname, '/_design/demo/_view/by-key')
+
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      const payload = JSON.stringify({
+        total_rows: expectedRows.length,
+        rows: expectedRows
+      })
+      const chunkSize = 7
+      for (let i = 0; i < payload.length; i += chunkSize) {
+        res.write(payload.slice(i, i + chunkSize))
+      }
+      res.end()
+    })
+
+    t.after(async () => {
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    })
+
+    const { port } = server.address() as AddressInfo
+    const rows: unknown[] = []
+
+    await queryStream(
+      { couch: `http://127.0.0.1:${port}` },
+      '_design/demo/_view/by-key',
+      {},
+      row => {
+        const matchedRow = expectedRows.find(r => r.id === row.id)
+        assert.ok(matchedRow)
+        assert.deepStrictEqual(row, matchedRow)
+        rows.push(row)
+      }
+    )
+
+    assert.deepStrictEqual(rows, expectedRows)
+  })
+
+  test('queryStream works with bindConfig', async t => {
+    const expectedRows = [
+      { id: 'row-1', key: 'row-1', value: { count: 1 } },
+      { id: 'row-2', key: 'row-2', value: { count: 2 } }
+    ]
+
+    // @ts-expect-error testing server
+    const server = await startServer((req, res) => {
+      res.on('error', () => {})
+      const requestUrl = new URL(req.url ?? '/', `http://${req.headers.host}`)
+      assert.strictEqual(req.method, 'GET')
+      assert.strictEqual(requestUrl.pathname, '/_design/demo/_view/by-key')
+
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      const payload = JSON.stringify({
+        total_rows: expectedRows.length,
+        rows: expectedRows
+      })
+      const chunkSize = 7
+      for (let i = 0; i < payload.length; i += chunkSize) {
+        res.write(payload.slice(i, i + chunkSize))
+      }
+      res.end()
+    })
+
+    t.after(async () => {
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    })
+
+    const { port } = server.address() as AddressInfo
+
+    const rows: unknown[] = []
+
+    const db = bindConfig({ couch: `http://127.0.0.1:${port}` })
+
+    await db.queryStream('_design/demo/_view/by-key', {}, row => {
+      const matchedRow = expectedRows.find(r => r.id === row.id)
+      assert.ok(matchedRow)
+      assert.deepStrictEqual(row, matchedRow)
+      rows.push(row)
+    })
+
+    assert.deepStrictEqual(rows, expectedRows)
+  })
+
+  test('queryStream works with options chaining', async t => {
+    const expectedRows = [
+      { id: 'row-1', key: 'row-1', value: { count: 1 } },
+      { id: 'row-2', key: 'row-2', value: { count: 2 } }
+    ]
+
+    // @ts-expect-error testing server
+    const server = await startServer((req, res) => {
+      res.on('error', () => {})
+      const requestUrl = new URL(req.url ?? '/', `http://${req.headers.host}`)
+      assert.strictEqual(req.method, 'GET')
+      assert.strictEqual(requestUrl.pathname, '/_design/demo/_view/by-key')
+
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      const payload = JSON.stringify({
+        total_rows: expectedRows.length,
+        rows: expectedRows
+      })
+      const chunkSize = 7
+      for (let i = 0; i < payload.length; i += chunkSize) {
+        res.write(payload.slice(i, i + chunkSize))
+      }
+      res.end()
+    })
+
+    t.after(async () => {
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    })
+
+    const { port } = server.address() as AddressInfo
+    const rows: unknown[] = []
+
+    const db = bindConfig({ couch: `http://127.0.0.1:${port}` })
+
+    await db.options({ logger: console }).queryStream('_design/demo/_view/by-key', {}, row => {
+      const matchedRow = expectedRows.find(r => r.id === row.id)
+      assert.ok(matchedRow)
+      assert.deepStrictEqual(row, matchedRow)
+      rows.push(row)
+    })
+
+    assert.deepStrictEqual(rows, expectedRows)
+  })
+
+  test('queryStream handles empty result sets', async t => {
+    // @ts-expect-error testing server
+    const server = await startServer((_, res) => {
+      res.on('error', () => {})
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.write('{"rows":[]}')
+      res.end()
+    })
+
+    t.after(async () => {
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    })
+
+    const { port } = server.address() as AddressInfo
+    let rowCount = 0
+
+    await queryStream(
+      { couch: `http://127.0.0.1:${port}` },
+      '_design/demo/_view/by-key',
+      {},
+      () => {
+        rowCount++
+      }
+    )
+
+    assert.strictEqual(rowCount, 0)
+  })
+
+  test('queryStream rejects when row handler throws', async t => {
+    // @ts-expect-error testing server
+    const server = await startServer((_, res) => {
+      res.on('error', () => {})
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.write('{"rows":[{"id":"broken","value":42}]}')
+      res.end()
+    })
+
+    t.after(async () => {
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    })
+
+    const { port } = server.address() as AddressInfo
+    const handlerError = new Error('row-failure')
+
+    await assert.rejects(
+      queryStream({ couch: `http://127.0.0.1:${port}` }, '_design/demo/_view/error', {}, () => {
+        throw handlerError
+      }),
+      error => {
+        assert.strictEqual(error, handlerError)
+        return true
+      }
+    )
+  })
+})

package/impl/sugar/lock.mts

@@ -0,0 +1,103 @@
+import { LockOptions } from '../../schema/sugar/lock.mts'
+import { put } from '../put.mts'
+import { get } from '../get.mts'
+import { createLogger } from '../utils/logger.mts'
+import { CouchConfig, type CouchConfigInput } from '../../schema/config.mts'
+import { isConflictError } from '../utils/errors.mts'
+
+/**
+ * Create a lock document for the specified document ID.
+ * Returns true if the lock was created, false if locking is disabled or a conflict occurred.
+ *
+ * @param configInput CouchDB configuration
+ * @param docId The document ID to lock
+ * @param lockOptions Locking options
+ *
+ * @return True if the lock was created, false otherwise
+ */
+export async function createLock(
+  configInput: CouchConfigInput,
+  docId: string,
+  lockOptions: LockOptions
+): Promise<boolean> {
+  const config = CouchConfig.parse(configInput)
+  const options = LockOptions.parse(lockOptions)
+
+  const logger = createLogger(config)
+
+  if (!options.enableLocking) {
+    logger.debug('Locking disabled, returning true without creating lock')
+    return true
+  }
+
+  const _id = `lock-${docId}`
+  const lock = {
+    _id,
+    type: 'lock',
+    locks: docId,
+    lockedAt: new Date().toISOString(),
+    lockedBy: options.username
+  }
+
+  try {
+    const result = await put(config, lock)
+    logger.info(`Lock created for ${docId} by ${options.username}`)
+    return result.ok === true
+  } catch (error) {
+    if (isConflictError(error)) {
+      logger.warn(`Lock conflict for ${docId} - already locked`)
+    } else {
+      logger.error(`Error creating lock for ${docId}:`, error)
+    }
+    return false
+  }
+}
+
+/**
+ * Remove the lock document for the specified document ID if owned by the caller.
+ *
+ * @param configInput CouchDB configuration
+ * @param docId The document ID to unlock
+ * @param lockOptions Locking options
+ *
+ * @return Promise that resolves when the unlock operation is complete
+ */
+export async function removeLock(
+  configInput: CouchConfigInput,
+  docId: string,
+  lockOptions: LockOptions
+): Promise<void> {
+  const config = CouchConfig.parse(configInput)
+  const options = LockOptions.parse(lockOptions)
+  const logger = createLogger(config)
+
+  if (!options.enableLocking) {
+    logger.debug('Locking disabled, skipping unlock')
+    return
+  }
+
+  if (!docId) {
+    logger.warn('No docId provided for unlock')
+    return
+  }
+
+  const _id = `lock-${docId}`
+  const existingLock = await get(config, _id)
+
+  if (!existingLock) {
+    logger.debug(`No lock found for ${docId}`)
+    return
+  }
+
+  if (existingLock.lockedBy !== options.username) {
+    logger.warn(`Cannot remove lock for ${docId} - owned by ${existingLock.lockedBy}`)
+    return
+  }
+
+  try {
+    await put(config, { ...existingLock, _deleted: true })
+    logger.info(`Lock removed for ${docId}`)
+  } catch (error) {
+    logger.error(`Error removing lock for ${docId}:`, error)
+  }
+}

package/impl/sugar/lock.test.mts

@@ -0,0 +1,113 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import needle from 'needle'
+import type { CouchConfigInput } from '../../schema/config.mts'
+import { createLock, removeLock } from './lock.mts'
+import { TEST_DB_URL } from '../../test/setup-db.mts'
+
+const baseConfig: CouchConfigInput = {
+  couch: TEST_DB_URL,
+  useConsoleLogger: true
+}
+
+async function fetchLockDoc(docId: string) {
+  return await needle('get', `${TEST_DB_URL}/lock-${docId}`, null, {
+    json: true
+  })
+}
+
+suite('lock', () => {
+  test('integration with pouchdb-server', async t => {
+    await t.test('creates a lock document when enabled', async () => {
+      const docId = `lock-creates-${Date.now()}`
+      const created = await createLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'alice'
+      })
+      assert.strictEqual(created, true)
+
+      const response = await fetchLockDoc(docId)
+      assert.strictEqual(response.statusCode, 200)
+      const body = response.body as { lockedBy: string; locks: string }
+      assert.strictEqual(body.lockedBy, 'alice')
+      assert.strictEqual(body.locks, docId)
+    })
+
+    await t.test('returns true without writing when locking disabled', async () => {
+      const docId = `lock-disabled-${Date.now()}`
+      const created = await createLock(baseConfig, docId, {
+        enableLocking: false,
+        username: 'anyone'
+      })
+      assert.strictEqual(created, true)
+
+      const response = await fetchLockDoc(docId)
+      assert.strictEqual(response.statusCode, 404)
+    })
+
+    await t.test('returns false on conflict and keeps existing lock', async () => {
+      const docId = `lock-conflict-${Date.now()}`
+      await createLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'alice'
+      })
+      const created = await createLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'bob'
+      })
+      assert.strictEqual(created, false)
+
+      const response = await fetchLockDoc(docId)
+      assert.strictEqual(response.statusCode, 200)
+      const body = response.body as { lockedBy: string }
+      assert.strictEqual(body.lockedBy, 'alice')
+    })
+
+    await t.test('removes lock when owned by caller', async () => {
+      const docId = `lock-remove-${Date.now()}`
+      await createLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'alice'
+      })
+      await removeLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'alice'
+      })
+
+      const response = await fetchLockDoc(docId)
+      assert.strictEqual(response.statusCode, 404)
+    })
+
+    await t.test('skips removal when lock owned by someone else', async () => {
+      const docId = `lock-remove-others-${Date.now()}`
+      await createLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'alice'
+      })
+      await removeLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'bob'
+      })
+
+      const response = await fetchLockDoc(docId)
+      assert.strictEqual(response.statusCode, 200)
+      const body = response.body as { lockedBy: string }
+      assert.strictEqual(body.lockedBy, 'alice')
+    })
+
+    await t.test('respects disabled removal', async () => {
+      const docId = `lock-disabled-remove-${Date.now()}`
+      await createLock(baseConfig, docId, {
+        enableLocking: true,
+        username: 'alice'
+      })
+      await removeLock(baseConfig, docId, {
+        enableLocking: false,
+        username: 'alice'
+      })
+
+      const response = await fetchLockDoc(docId)
+      assert.strictEqual(response.statusCode, 200)
+    })
+  })
+})

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