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

package/impl/utils/parseRows.test.mts

@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { z } from 'zod'
+import { parseRows } from './parseRows.mts'
+
+const docSchema = z.looseObject({
+  _id: z.string(),
+  count: z.number()
+})
+
+const keySchema = z.number()
+
+const valueSchema = z.looseObject({
+  rev: z.string()
+})
+
+suite('parseRows', () => {
+  test('throws when rows is not an array', async () => {
+    await assert.rejects(
+      () =>
+        parseRows(
+          {},
+          {
+            docSchema,
+            keySchema,
+            valueSchema,
+            onInvalidDoc: 'throw'
+          }
+        ),
+      err => err instanceof Error && err.message === 'invalid rows format'
+    )
+  })
+
+  test('parses rows and validates documents', async () => {
+    const rows = [
+      {
+        id: 'doc-valid',
+        key: 1,
+        value: { rev: '1-abc' },
+        doc: {
+          _id: 'doc-valid',
+          count: 42
+        }
+      },
+      {
+        id: 'doc-missing',
+        key: 2,
+        error: 'not_found',
+        doc: null,
+        value: { rev: '1-missing' }
+      }
+    ]
+
+    const result = await parseRows(rows, {
+      docSchema,
+      keySchema,
+      valueSchema,
+      onInvalidDoc: 'throw'
+    })
+
+    assert.strictEqual(result.length, 2)
+    const [valid, missing] = result
+    assert.strictEqual(valid?.id, 'doc-valid')
+    assert.strictEqual(valid?.doc?.count, 42)
+    assert.strictEqual(valid?.key, 1)
+    assert.strictEqual(valid?.value?.rev, '1-abc')
+    assert.strictEqual(missing?.id, 'doc-missing')
+    assert.strictEqual(missing?.error, 'not_found')
+    assert.strictEqual(missing?.key, 2)
+    assert.strictEqual(missing?.value?.rev, '1-missing')
+    assert.strictEqual(missing?.doc, null)
+  })
+
+  test('skips invalid documents when requested', async () => {
+    const rows = [
+      {
+        id: 'doc-valid',
+        key: 1,
+        value: { rev: '1-valid' },
+        doc: {
+          _id: 'doc-valid',
+          count: 7
+        }
+      },
+      {
+        id: 'doc-invalid',
+        key: 2,
+        value: { rev: '1-invalid' },
+        doc: {
+          _id: 'doc-invalid',
+          count: 'nope'
+        }
+      }
+    ]
+
+    const result = await parseRows(rows, {
+      docSchema,
+      keySchema,
+      valueSchema,
+      onInvalidDoc: 'skip'
+    })
+
+    assert.strictEqual(result.length, 1)
+    assert.strictEqual(result[0]?.id, 'doc-valid')
+    assert.strictEqual(result[0]?.doc?.count, 7)
+    assert.strictEqual(result[0]?.key, 1)
+  })
+
+  test('throws when a document fails validation with onInvalidDoc=throw', async () => {
+    const rows = [
+      {
+        id: 'doc-invalid',
+        key: 1,
+        value: { rev: '1-invalid' },
+        doc: {
+          _id: 'doc-invalid',
+          count: 'nope'
+        }
+      }
+    ]
+
+    await assert.rejects(
+      () =>
+        parseRows(rows, {
+          docSchema,
+          keySchema,
+          valueSchema,
+          onInvalidDoc: 'throw'
+        }),
+      err => Array.isArray(err)
+    )
+  })
+
+  test('throws when key fails validation', async () => {
+    const rows = [
+      {
+        id: 'doc-valid',
+        key: 'invalid',
+        value: { rev: '1-valid' },
+        doc: {
+          _id: 'doc-valid',
+          count: 7
+        }
+      }
+    ]
+
+    await assert.rejects(
+      () =>
+        parseRows(rows, {
+          docSchema,
+          keySchema,
+          valueSchema,
+          onInvalidDoc: 'throw'
+        }),
+      err => Array.isArray(err)
+    )
+  })
+
+  test('throws when value fails validation', async () => {
+    const rows = [
+      {
+        id: 'doc-valid',
+        key: 1,
+        value: { rev: 123 },
+        doc: {
+          _id: 'doc-valid',
+          count: 7
+        }
+      }
+    ]
+
+    await assert.rejects(
+      () =>
+        parseRows(rows, {
+          docSchema,
+          keySchema,
+          valueSchema,
+          onInvalidDoc: 'throw'
+        }),
+      err => Array.isArray(err)
+    )
+  })
+})

package/impl/utils/queryBuilder.mts

@@ -0,0 +1,173 @@
+import type { ViewOptions } from '../../schema/couch/couch.input.schema.ts'
+
+/**
+ * A builder class for constructing CouchDB view query options.
+ * Provides a fluent API for setting various query parameters.
+ * @example
+ * const queryOptions = new QueryBuilder()
+ *   .limit(10)
+ *   .include_docs()
+ *   .startKey('someKey')
+ *   .build();
+ * @see SimpleViewOptions for the full list of options.
+ *
+ * @remarks
+ * Each method corresponds to a CouchDB view option and returns the builder instance for chaining.
+ *
+ * @returns The constructed SimpleViewOptions object.
+ */
+export class QueryBuilder {
+  #options: ViewOptions = {}
+
+  descending(descending = true): this {
+    this.#options.descending = descending
+    return this
+  }
+
+  endkey_docid(endkeyDocId: NonNullable<ViewOptions['endkey_docid']>): this {
+    this.#options.endkey_docid = endkeyDocId
+    return this
+  }
+
+  /**
+   * Alias for endkey_docid
+   */
+  end_key_doc_id(endkeyDocId: NonNullable<ViewOptions['endkey_docid']>): this {
+    this.#options.endkey_docid = endkeyDocId
+    return this
+  }
+
+  endkey(endkey: ViewOptions['endkey']): this {
+    this.#options.endkey = endkey
+    return this
+  }
+
+  /**
+   * Alias for endkey
+   */
+  endKey(endkey: ViewOptions['endkey']): this {
+    this.#options.endkey = endkey
+    return this
+  }
+
+  /**
+   * Alias for endkey
+   */
+  end_key(endkey: ViewOptions['endkey']): this {
+    this.#options.endkey = endkey
+    return this
+  }
+
+  group(group = true): this {
+    this.#options.group = group
+    return this
+  }
+
+  group_level(level: NonNullable<ViewOptions['group_level']>): this {
+    this.#options.group_level = level
+    return this
+  }
+
+  include_docs(includeDocs = true): this {
+    this.#options.include_docs = includeDocs
+    return this
+  }
+
+  inclusive_end(inclusiveEnd = true): this {
+    this.#options.inclusive_end = inclusiveEnd
+    return this
+  }
+
+  key(key: ViewOptions['key']): this {
+    this.#options.key = key
+    return this
+  }
+
+  keys(keys: NonNullable<ViewOptions['keys']>): this {
+    this.#options.keys = keys
+    return this
+  }
+
+  limit(limit: NonNullable<ViewOptions['limit']>): this {
+    this.#options.limit = limit
+    return this
+  }
+
+  reduce(reduce = true): this {
+    this.#options.reduce = reduce
+    return this
+  }
+
+  skip(skip: NonNullable<ViewOptions['skip']>): this {
+    this.#options.skip = skip
+    return this
+  }
+
+  sorted(sorted = true): this {
+    this.#options.sorted = sorted
+    return this
+  }
+
+  stable(stable = true): this {
+    this.#options.stable = stable
+    return this
+  }
+
+  startkey(startkey: ViewOptions['startkey']): this {
+    this.#options.startkey = startkey
+    return this
+  }
+
+  /**
+   * Alias for startkey
+   */
+  startKey(startkey: ViewOptions['startkey']): this {
+    this.#options.startkey = startkey
+    return this
+  }
+
+  /**
+   * Alias for startkey
+   */
+  start_key(startkey: ViewOptions['startkey']): this {
+    this.#options.startkey = startkey
+    return this
+  }
+
+  startkey_docid(startkeyDocId: NonNullable<ViewOptions['startkey_docid']>): this {
+    this.#options.startkey_docid = startkeyDocId
+    return this
+  }
+
+  /**
+   * Alias for startkey_docid
+   */
+  start_key_doc_id(startkeyDocId: NonNullable<ViewOptions['startkey_docid']>): this {
+    this.#options.startkey_docid = startkeyDocId
+    return this
+  }
+
+  update(update: NonNullable<ViewOptions['update']>): this {
+    this.#options.update = update
+    return this
+  }
+
+  update_seq(updateSeq = true): this {
+    this.#options.update_seq = updateSeq
+    return this
+  }
+
+  /**
+   * Builds and returns the ViewOptions object.
+   */
+  build(): ViewOptions {
+    return { ...this.#options }
+  }
+}
+
+type AssertViewOptionsCovered =
+  Exclude<keyof ViewOptions, keyof QueryBuilder> extends never ? true : never
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _assertViewOptionsCovered: AssertViewOptionsCovered = true
+
+export const createQuery = (): QueryBuilder => new QueryBuilder()

package/impl/utils/queryBuilder.test.mts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { QueryBuilder, createQuery } from './queryBuilder.mts'
+
+suite('QueryBuilder', () => {
+  test('build returns populated options', () => {
+    const options = new QueryBuilder()
+      .descending(false)
+      .endkey_docid('end-doc')
+      .endkey(['range-end'])
+      .group(false)
+      .group_level(2)
+      .include_docs(true)
+      .inclusive_end(false)
+      .key('primary')
+      .keys(['k1', { foo: 'bar' }])
+      .limit(10)
+      .reduce(false)
+      .skip(5)
+      .sorted(false)
+      .stable(true)
+      .startkey(['range-start'])
+      .startkey_docid('start-doc')
+      .update('lazy')
+      .update_seq(true)
+      .build()
+
+    assert.deepStrictEqual(options, {
+      descending: false,
+      endkey_docid: 'end-doc',
+      endkey: ['range-end'],
+      group: false,
+      group_level: 2,
+      include_docs: true,
+      inclusive_end: false,
+      key: 'primary',
+      keys: ['k1', { foo: 'bar' }],
+      limit: 10,
+      reduce: false,
+      skip: 5,
+      sorted: false,
+      stable: true,
+      startkey: ['range-start'],
+      startkey_docid: 'start-doc',
+      update: 'lazy',
+      update_seq: true
+    })
+  })
+
+  test('alias methods map to canonical fields', () => {
+    const options = new QueryBuilder()
+      .endKey(['alias-end'])
+      .startKey(['alias-start'])
+      .end_key_doc_id('alias-end-doc')
+      .start_key_doc_id('alias-start-doc')
+      .end_key(['duplicate-end'])
+      .start_key(['duplicate-start'])
+      .build()
+
+    assert.deepStrictEqual(options, {
+      endkey: ['duplicate-end'],
+      startkey: ['duplicate-start'],
+      endkey_docid: 'alias-end-doc',
+      startkey_docid: 'alias-start-doc'
+    })
+  })
+
+  test('build returns a defensive copy', () => {
+    const builder = new QueryBuilder().limit(5)
+    const first = builder.build()
+    first.limit = 42
+
+    const second = builder.build()
+
+    assert.notStrictEqual(first, second)
+    assert.strictEqual(second.limit, 5)
+  })
+
+  test('createQuery returns a builder instance', () => {
+    const builder = createQuery()
+    assert.ok(builder instanceof QueryBuilder)
+  })
+})

package/impl/utils/queryString.mts

@@ -0,0 +1,44 @@
+import { ViewOptions } from '../../schema/couch/couch.input.schema.ts'
+
+const KEYS_TO_QUOTE: (keyof ViewOptions)[] = [
+  'endkey_docid',
+  'endkey',
+  'key',
+  'keys',
+  'startkey',
+  'startkey_docid',
+  'update'
+]
+
+/**
+ * Serialize CouchDB view options into a URL-safe query string, quoting values CouchDB expects as JSON.
+ * @param options The view options to serialize
+ * @param params The list of option keys that require JSON quoting
+ * @returns The serialized query string
+ */
+export function queryString(options: ViewOptions = {}): string {
+  const searchParams = new URLSearchParams()
+  const parsedOptions = ViewOptions.parse(options)
+  Object.entries(parsedOptions).forEach(([key, rawValue]) => {
+    let value = rawValue
+    if (KEYS_TO_QUOTE.includes(key as keyof ViewOptions)) {
+      if (typeof value === 'string') value = `"${value}"`
+      if (Array.isArray(value)) {
+        value =
+          '[' +
+          value
+            .map(i => {
+              if (i === null) return 'null'
+              if (typeof i === 'string') return `"${i}"`
+              if (typeof i === 'object' && Object.keys(i).length === 0) return '{}'
+              if (typeof i === 'object') return JSON.stringify(i)
+              return i
+            })
+            .join(',') +
+          ']'
+      }
+    }
+    searchParams.set(key, String(value))
+  })
+  return searchParams.toString()
+}

package/impl/utils/queryString.test.mts

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict'
+import test, { suite } from 'node:test'
+import { queryString } from './queryString.mts'
+import type { ViewOptions } from '../../schema/couch/couch.input.schema.ts'
+
+const keysToQuote: Array<keyof ViewOptions> = [
+  'endkey_docid',
+  'endkey',
+  'key',
+  'keys',
+  'startkey',
+  'startkey_docid',
+  'update'
+]
+
+suite('queryString', () => {
+  test('queryString quotes string values for KEYS_TO_QUOTE except keys array', () => {
+    const encodedByKey = new Map<string, string | null>()
+
+    for (const key of keysToQuote) {
+      if (key === 'keys') continue
+      const optionValue: ViewOptions = {
+        [key]: key === 'update' ? 'lazy' : 'banana'
+      } as ViewOptions
+      const encoded = queryString(optionValue)
+      const params = new URLSearchParams(encoded)
+      encodedByKey.set(key as string, params.get(key as string))
+    }
+
+    assert.deepEqual(Object.fromEntries(encodedByKey), {
+      endkey_docid: '"banana"',
+      endkey: '"banana"',
+      key: '"banana"',
+      startkey: '"banana"',
+      startkey_docid: '"banana"',
+      update: '"lazy"'
+    })
+  })
+
+  test('queryString leaves primitive options outside KEYS_TO_QUOTE unchanged', () => {
+    const encoded = queryString({ descending: true })
+    const params = new URLSearchParams(encoded)
+    assert.equal(params.get('descending'), 'true')
+  })
+
+  test('queryString stringifies array values for keys option', () => {
+    const encoded = queryString({
+      keys: ['alpha', null, 42, {}, { foo: 'bar' }]
+    })
+    const params = new URLSearchParams(encoded)
+    assert.equal(params.get('keys'), '["alpha",null,42,{}, {"foo":"bar"}]'.replace(' ', ''))
+  })
+})

package/impl/{trackedEmitter.mjs → utils/trackedEmitter.mts}

@@ -1,21 +1,23 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
 import { EventEmitter } from 'events'
 
 export class TrackedEmitter extends EventEmitter {
   // create a constructor with some options
-  constructor (options) {
+  constructor(options) {
     super(options)
     if (options.delay) this.delay = options.delay
   }
 
-  emit (event, ...args) {
+  emit(event, ...args) {
     const listeners = this.listeners(event)
     let completed = 0
 
-    return new Promise((resolve) => {
+    return new Promise(resolve => {
       if (!listeners || listeners.length === 0) {
         return resolve() // no listeners? no delay
       }
-      listeners.forEach((listener) => {
+      listeners.forEach(listener => {
         listener(...args)
         completed++
         if (completed === listeners.length) {
@@ -27,7 +29,7 @@ export class TrackedEmitter extends EventEmitter {
   }
 }
 
-export const setupEmitter = (config) => {
-  if (!config._emitter) return ({ emit: async () => {} })
-  return config._emitter
+export const setupEmitter = config => {
+  if (!config['~emitter']) return { emit: async () => {} }
+  return config['~emitter']
 }

package/impl/utils/transactionErrors.mts

@@ -0,0 +1,71 @@
+export class TransactionSetupError extends Error {
+  details: Record<string, unknown>
+
+  constructor(message: string, details: Record<string, unknown> = {}) {
+    super(message)
+    this.name = 'TransactionSetupError'
+    this.details = details
+  }
+}
+
+export class TransactionVersionConflictError extends Error {
+  conflictingIds: string[]
+
+  constructor(conflictingIds: string[]) {
+    super(`Revision mismatch for documents: ${conflictingIds.join(', ')}`)
+    this.name = 'TransactionVersionConflictError'
+    this.conflictingIds = conflictingIds
+  }
+}
+
+export class TransactionBulkOperationError extends Error {
+  failedDocs: {
+    ok?: boolean | null
+    id?: string | null
+    rev?: string | null
+    error?: string | null
+    reason?: string | null
+  }[]
+
+  constructor(
+    failedDocs: Array<{
+      ok?: boolean | null
+      id?: string | null
+      rev?: string | null
+      error?: string | null
+      reason?: string | null
+    }>
+  ) {
+    super(`Failed to save documents: ${failedDocs.map(d => d.id).join(', ')}`)
+    this.name = 'TransactionBulkOperationError'
+    this.failedDocs = failedDocs
+  }
+}
+
+export class TransactionRollbackError extends Error {
+  originalError: Error
+  rollbackResults: {
+    ok?: boolean | null
+    id?: string | null
+    rev?: string | null
+    error?: string | null
+    reason?: string | null
+  }[]
+
+  constructor(
+    message: string,
+    originalError: Error,
+    rollbackResults: Array<{
+      ok?: boolean | null
+      id?: string | null
+      rev?: string | null
+      error?: string | null
+      reason?: string | null
+    }>
+  ) {
+    super(message)
+    this.name = 'TransactionRollbackError'
+    this.originalError = originalError
+    this.rollbackResults = rollbackResults
+  }
+}