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

package/impl/utils/response.mts

@@ -0,0 +1,50 @@
+export const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return value !== null && typeof value === 'object'
+}
+
+export type CouchSuccessProfile =
+  | 'bulkGet'
+  | 'bulkSave'
+  | 'changesFeed'
+  | 'database'
+  | 'documentDelete'
+  | 'documentRead'
+  | 'documentWrite'
+  | 'viewQuery'
+  | 'viewStream'
+
+const SUCCESS_STATUS_CODES: Record<CouchSuccessProfile, readonly number[]> = {
+  bulkGet: [200],
+  bulkSave: [201, 202],
+  changesFeed: [200],
+  database: [200],
+  documentDelete: [200, 202],
+  documentRead: [200],
+  documentWrite: [200, 201, 202],
+  viewQuery: [200],
+  viewStream: [200]
+}
+
+export const getReason = (value: unknown, fallback: string) => {
+  if (!isRecord(value) || typeof value.reason !== 'string') {
+    return fallback
+  }
+
+  return value.reason
+}
+
+export const getCouchError = (value: unknown) => {
+  if (!isRecord(value) || typeof value.error !== 'string') {
+    return undefined
+  }
+
+  return value.error
+}
+
+export const getSuccessStatusCodes = (profile: CouchSuccessProfile) => {
+  return SUCCESS_STATUS_CODES[profile]
+}
+
+export const isSuccessStatusCode = (profile: CouchSuccessProfile, statusCode: number) => {
+  return SUCCESS_STATUS_CODES[profile].includes(statusCode)
+}

package/impl/utils/transactionErrors.mts

@@ -1,24 +1,28 @@
-export class TransactionSetupError extends Error {
+import { OperationError } from './errors.mts'
+
+export class TransactionSetupError extends OperationError {
   details: Record<string, unknown>
 
   constructor(message: string, details: Record<string, unknown> = {}) {
-    super(message)
+    super(message, { category: 'transaction' })
     this.name = 'TransactionSetupError'
     this.details = details
   }
 }
 
-export class TransactionVersionConflictError extends Error {
+export class TransactionVersionConflictError extends OperationError {
   conflictingIds: string[]
 
   constructor(conflictingIds: string[]) {
-    super(`Revision mismatch for documents: ${conflictingIds.join(', ')}`)
+    super(`Revision mismatch for documents: ${conflictingIds.join(', ')}`, {
+      category: 'transaction'
+    })
     this.name = 'TransactionVersionConflictError'
     this.conflictingIds = conflictingIds
   }
 }
 
-export class TransactionBulkOperationError extends Error {
+export class TransactionBulkOperationError extends OperationError {
   failedDocs: {
     ok?: boolean | null
     id?: string | null
@@ -36,13 +40,15 @@ export class TransactionBulkOperationError extends Error {
       reason?: string | null
     }>
   ) {
-    super(`Failed to save documents: ${failedDocs.map(d => d.id).join(', ')}`)
+    super(`Failed to save documents: ${failedDocs.map(d => d.id).join(', ')}`, {
+      category: 'transaction'
+    })
     this.name = 'TransactionBulkOperationError'
     this.failedDocs = failedDocs
   }
 }
 
-export class TransactionRollbackError extends Error {
+export class TransactionRollbackError extends OperationError {
   originalError: Error
   rollbackResults: {
     ok?: boolean | null
@@ -63,7 +69,7 @@ export class TransactionRollbackError extends Error {
       reason?: string | null
     }>
   ) {
-    super(message)
+    super(message, { category: 'transaction' })
     this.name = 'TransactionRollbackError'
     this.originalError = originalError
     this.rollbackResults = rollbackResults

package/impl/utils/url.mts

@@ -0,0 +1,21 @@
+const ensureDirectoryUrl = (value: string | URL) => {
+  const url = new URL(value)
+
+  if (!url.pathname.endsWith('/')) {
+    url.pathname = `${url.pathname}/`
+  }
+
+  return url
+}
+
+export const createCouchDbUrl = (value: string | URL) => {
+  return new URL(value)
+}
+
+export const createCouchPathUrl = (path: string, base: string | URL) => {
+  return new URL(path, ensureDirectoryUrl(base))
+}
+
+export const createCouchDocUrl = (docId: string, base: string | URL) => {
+  return new URL(encodeURIComponent(docId), ensureDirectoryUrl(base))
+}

package/index.mts

@@ -46,6 +46,15 @@ export {
   removeLock
 }
 
+export {
+  ConflictError,
+  HideABedError,
+  NotFoundError,
+  OperationError,
+  RetryableError,
+  ValidationError
+} from './impl/utils/errors.mts'
+
 export type {
   BulkGetBound,
   BulkGetDictionaryBound,
@@ -70,10 +79,18 @@ export type {
   ViewRowValidated
 } from './schema/couch/couch.output.schema.ts'
 export type { RetryOptions } from './impl/retry.mts'
-export type { NetworkError, RetryableError, NotFoundError } from './impl/utils/errors.mts'
+export type {
+  ErrorCategory,
+  ErrorOperation,
+  HideABedErrorOptions,
+  NetworkError,
+  ValidationErrorOptions
+} from './impl/utils/errors.mts'
 export type { OnRow } from './impl/stream.mts'
-export type { CouchConfig, CouchConfigInput } from './schema/config.mts'
+export type { CouchAuth, CouchAuthInput, CouchConfig, CouchConfigInput } from './schema/config.mts'
+export type { Dispatcher, RequestOptions, RequestOptionsInput } from './schema/request.mts'
 export type { LockOptions, LockOptionsInput, LockDoc } from './schema/sugar/lock.mts'
+export type { WatchHandle, WatchListener } from './impl/sugar/watch.mts'
 export type {
   WatchOptions as WatchOptionsSchema,
   WatchOptionsInput

package/migration_guides/v7.md

@@ -0,0 +1,353 @@
+# hide-a-bed v7 Migration Guide
+
+## When to read this
+
+- Teams upgrading from any `hide-a-bed` v6 release to the current v7 beta line.
+- Consumers who passed transport-specific `needle` options into config.
+- Consumers who used return payloads like `{ ok: false, error: 'conflict' }` for control flow.
+- Teams that validate docs or rows and need to update error handling.
+
+## Scope
+
+This guide covers the behavior changes between the `6.0.0` release and the current v7 work in this branch. The biggest shift is the move from `needle` to native `fetch`, but the upgrade also changes config validation, request controls, and several failure paths.
+
+## Upgrade checklist
+
+1. Update `hide-a-bed` to v7 and run your tests on a Node runtime that matches the package manifest for `client/`.
+2. Remove every use of `config.needleOpts`.
+3. Move CouchDB credentials out of the Couch URL and into `config.auth`.
+4. Move timeout, abort, and dispatcher settings into `config.request`.
+5. Update any code that inspects `{ ok: false, error: ... }` from single-document helpers to catch typed errors instead.
+6. Update any validation error handling that expected raw schema issues instead of a `ValidationError`.
+7. Re-test streaming and watch flows with abort/cancellation, especially if you previously relied on request-library behavior.
+
+## Breaking changes
+
+### 1. `needleOpts` is gone
+
+v6 accepted transport-specific options through `config.needleOpts`. v7 validates config strictly and rejects `needleOpts`.
+
+Before:
+
+```ts
+const config = {
+  couch: 'http://localhost:5984/mydb',
+  needleOpts: {
+    timeout: 5000,
+    username: process.env.COUCHDB_USER,
+    password: process.env.COUCHDB_PASSWORD
+  }
+}
+```
+
+After:
+
+```ts
+const config = {
+  couch: 'http://localhost:5984/mydb',
+  auth: {
+    username: process.env.COUCHDB_USER!,
+    password: process.env.COUCHDB_PASSWORD!
+  },
+  request: {
+    timeout: 5000
+  }
+}
+```
+
+What changed:
+
+- `config.auth` is the supported way to send basic auth credentials.
+- `config.request` is the supported way to pass native fetch controls.
+- Only these request fields are supported: `signal`, `timeout`, and `dispatcher`.
+- Unknown keys under `config.request` now fail validation.
+
+### 2. Couch URLs with embedded credentials are rejected
+
+v6 accepted a `couch` string like `http://alice:secret@localhost:5984/mydb`. v7 rejects config values with embedded credentials.
+
+Before:
+
+```ts
+const config = {
+  couch: 'http://alice:secret@localhost:5984/mydb'
+}
+```
+
+After:
+
+```ts
+const config = {
+  couch: 'http://localhost:5984/mydb',
+  auth: {
+    username: 'alice',
+    password: 'secret'
+  }
+}
+```
+
+### 3. Request controls moved to config-level `request`
+
+v7 uses native fetch internally, so request customization is intentionally much smaller than the old `needle` surface.
+
+Supported:
+
+- `config.request.signal`
+- `config.request.timeout`
+- `config.request.dispatcher`
+
+Not supported:
+
+- Per-call `request` overrides inside `get()` options, `query()` options, or `watchDocs()` options.
+- Any other transport-specific fields from `needle`.
+
+Use config overrides instead:
+
+```ts
+const db = bindConfig({
+  couch: 'http://localhost:5984/mydb',
+  request: { timeout: 5000 }
+})
+
+await db
+  .options({
+    request: {
+      timeout: 1000,
+      signal: abortController.signal
+    }
+  })
+  .get('doc-123')
+```
+
+### 4. Single-document write/delete helpers now throw typed errors
+
+Several v6 code paths returned parsed CouchDB payloads like `{ ok: false, error: 'conflict' }`. In v7 those same cases now throw.
+
+#### `put()`
+
+Before:
+
+```ts
+const result = await put(config, {
+  _id: 'doc-123',
+  _rev: 'stale-rev'
+})
+
+if (result.error === 'conflict') {
+  // handle stale rev
+}
+```
+
+After:
+
+```ts
+import { ConflictError } from 'hide-a-bed'
+
+try {
+  await put(config, {
+    _id: 'doc-123',
+    _rev: 'stale-rev'
+  })
+} catch (error) {
+  if (error instanceof ConflictError) {
+    console.log(error.docId)
+    console.log(error.statusCode)
+  } else {
+    throw error
+  }
+}
+```
+
+#### `remove()`
+
+Before:
+
+```ts
+const result = await remove(config, 'missing-doc', '1-deadbeef')
+
+if (result.error === 'not_found') {
+  // handle missing document
+}
+```
+
+After:
+
+```ts
+import { NotFoundError } from 'hide-a-bed'
+
+try {
+  await remove(config, 'missing-doc', '1-deadbeef')
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log(error.docId)
+  } else {
+    throw error
+  }
+}
+```
+
+#### `patch()` and `patchDangerously()`
+
+Before:
+
+- `patch()` returned a conflict-shaped response when `_rev` did not match.
+- `patchDangerously()` could return `{ ok: false, error: 'not_found' }` or a generic failure payload after retry exhaustion.
+
+After:
+
+- `patch()` throws `ConflictError` for stale revisions.
+- `patch()` throws `NotFoundError` when the document is missing.
+- `patchDangerously()` throws `NotFoundError` when the document is missing.
+- `patchDangerously()` throws `OperationError` when retries are exhausted.
+
+This means upgrade code should stop pattern-matching on `result.ok` for unhappy paths and switch to `try`/`catch`.
+
+### 5. Validation failures now throw `ValidationError`
+
+In v6, validation failures could bubble out as raw schema issues. In v7 they are wrapped in a first-class `ValidationError`.
+
+Affected helpers include:
+
+- `get()`
+- `getAtRev()`
+- `bulkGet()`
+- `bulkGetDictionary()`
+- `query()`
+
+Before:
+
+```ts
+try {
+  await get(config, 'doc-123', {
+    validate: { docSchema }
+  })
+} catch (issues) {
+  // issues might be the raw schema issue array
+}
+```
+
+After:
+
+```ts
+import { ValidationError } from 'hide-a-bed'
+
+try {
+  await get(config, 'doc-123', {
+    validate: { docSchema }
+  })
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log(error.docId)
+    console.log(error.operation)
+    console.log(error.issues)
+  } else {
+    throw error
+  }
+}
+```
+
+### 6. Request-level failures now use structured operational errors
+
+v7 adds exported error classes for request and CouchDB failures:
+
+- `HideABedError`
+- `ConflictError`
+- `NotFoundError`
+- `OperationError`
+- `RetryableError`
+- `ValidationError`
+
+These errors carry machine-readable fields such as:
+
+- `statusCode`
+- `docId`
+- `operation`
+- `couchError`
+- `retryable`
+
+This especially affects:
+
+- `query()`
+- `bulkGet()`
+- `bulkSave()`
+- `getDBInfo()`
+- `queryStream()`
+- `watchDocs()`
+
+Instead of parsing `error.message`, prefer branching on the class and metadata.
+
+### 7. `bulkSave([])` is now a hard error
+
+v6 threw a generic `Error('no docs provided')`. v7 throws an `OperationError` with message `Bulk save requires at least one document`.
+
+If you intentionally call `bulkSave()` with a maybe-empty array, guard it first:
+
+```ts
+if (docs.length > 0) {
+  await bulkSave(config, docs)
+}
+```
+
+### 8. Streaming and watch flows now respect `config.request`
+
+`queryStream()` and `watchDocs()` now run through the same native fetch layer as the rest of the client.
+
+Practical migration notes:
+
+- Aborting `config.request.signal` aborts the active stream request.
+- `watchDocs().stop()` aborts the active request instead of only destroying the old request object.
+- `watchDocs()` emits a single `end` when stopped or externally aborted.
+- Invalid `watchDocs()` input now throws `OperationError` instead of a generic `Error`.
+
+Example:
+
+```ts
+const controller = new AbortController()
+
+const watcher = watchDocs(
+  {
+    couch: 'http://localhost:5984/mydb',
+    request: { signal: controller.signal }
+  },
+  ['doc-1', 'doc-2'],
+  change => {
+    console.log(change.id)
+  }
+)
+
+controller.abort()
+```
+
+## What stays the same
+
+- The top-level CRUD, bulk, query, and stream helper names are unchanged.
+- `get()` still returns `null` on 404 by default, and still throws when `throwOnGetNotFound: true`.
+- Bulk APIs still report item-level failures inside their result payloads where that was already the contract.
+- `bindConfig()` and `withRetry()` remain the main composition helpers.
+- `watchDocs()` and `queryStream()` remain in the main package.
+
+## New exports worth using
+
+v7 newly exports runtime classes and types that make upgrade code cleaner:
+
+- Error classes: `ConflictError`, `HideABedError`, `NotFoundError`, `OperationError`, `RetryableError`, `ValidationError`
+- Config types: `CouchAuth`, `CouchAuthInput`, `RequestOptions`, `RequestOptionsInput`, `Dispatcher`
+- Watch types: `WatchHandle`, `WatchListener`
+
+## Suggested migration order
+
+1. Replace config construction first.
+2. Update single-document error handling next.
+3. Update validation error handling.
+4. Re-test watchers, streams, and timeout/abort behavior.
+5. Re-run integration tests against CouchDB or the stub package.
+
+## Verification checklist
+
+- No code still references `needleOpts`.
+- No Couch URLs still embed credentials.
+- All auth now flows through `config.auth`.
+- Timeouts and abort signals now flow through `config.request`.
+- `put()`, `remove()`, `patch()`, and `patchDangerously()` callers use `try`/`catch` for unhappy paths.
+- Validation callers catch `ValidationError` instead of assuming raw issues.
+- Streaming and watcher tests still pass with cancellation enabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hide-a-bed",
-  "version": "6.0.0",
+  "version": "7.0.0-beta.0",
   "description": "An abstraction over couchdb calls that includes easy mock/stubs with pouchdb",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -32,6 +32,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:watch": "tsc --noEmit --watch",
     "prepublishOnly": "npm run build",
+    "validate": "npm run format && npm run lint && npm run typecheck",
     "full": "npm run lint:fix && npm run build && npm run clean"
   },
   "repository": {
@@ -49,15 +50,14 @@
   },
   "homepage": "https://github.com/ryanramage/hide-a-bed#readme",
   "dependencies": {
-    "needle": "3.3.1",
     "stream-chain": "3.4.0",
     "stream-json": "1.9.1",
+    "undici-types": "7.24.3",
     "zod": "4.2.1"
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
-    "@types/needle": "3.3.0",
-    "@types/node": "22.19.3",
+    "@types/node": "24.12.0",
     "@types/stream-json": "1.7.8",
     "eslint": "9.39.2",
     "globals": "16.5.0",

package/schema/config.mts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { StandardSchemaV1 } from '../types/standard-schema.ts'
+import { RequestOptions } from './request.mts'
 
 const anyArgs = z.array(z.any())
 
@@ -12,46 +13,26 @@ const LoggerSchema = z
   })
   .or(z.function({ input: anyArgs, output: z.void() }))
 
-export const NeedleBaseOptions = z.object({
-  json: z.boolean(),
-  headers: z.record(z.string(), z.string()),
-  parse_response: z.boolean().optional()
+export const CouchAuth = z.strictObject({
+  username: z.string().describe('basic auth username for CouchDB requests'),
+  password: z.string().describe('basic auth password for CouchDB requests')
 })
-export type NeedleBaseOptionsSchema = z.infer<typeof NeedleBaseOptions>
 
-export const NeedleOptions = z.object({
-  json: z.boolean().optional(),
-  compressed: z.boolean().optional(),
-  follow_max: z.number().optional(),
-  follow_set_cookie: z.boolean().optional(),
-  follow_set_referer: z.boolean().optional(),
-  follow: z.number().optional(),
-  timeout: z.number().optional(),
-  read_timeout: z.number().optional(),
-  parse_response: z.boolean().optional(),
-  decode: z.boolean().optional(),
-  parse_cookies: z.boolean().optional(),
-  cookies: z.record(z.string(), z.string()).optional(),
-  headers: z.record(z.string(), z.string()).optional(),
-  auth: z.enum(['auto', 'digest', 'basic']).optional(),
-  username: z.string().optional(),
-  password: z.string().optional(),
-  proxy: z.string().optional(),
-  agent: z.any().optional(),
-  rejectUnauthorized: z.boolean().optional(),
-  output: z.string().optional(),
-  parse: z.boolean().optional(),
-  multipart: z.boolean().optional(),
-  open_timeout: z.number().optional(),
-  response_timeout: z.number().optional(),
-  keepAlive: z.boolean().optional()
+const CouchUrl = z.custom<string | URL>(value => {
+  try {
+    const url = new URL(value as string | URL)
+    return url.username === '' && url.password === ''
+  } catch {
+    return false
+  }
 })
 
 export const CouchConfig = z
   .strictObject({
+    auth: CouchAuth.optional().describe('basic auth credentials for CouchDB requests'),
     backoffFactor: z.number().optional().default(2).describe('multiplier for exponential backoff'),
     bindWithRetry: z.boolean().optional().default(true).describe('should we bind with retry'),
-    couch: z.string().describe('the url of the couch db'),
+    couch: CouchUrl.describe('URL of the couch db without embedded credentials'),
     initialDelay: z
       .number()
       .optional()
@@ -61,12 +42,12 @@ export const CouchConfig = z
       'logging interface supporting winston-like or simple function interface'
     ),
     maxRetries: z.number().optional().default(3).describe('maximum number of retry attempts'),
-    needleOpts: NeedleOptions.optional(),
+    request: RequestOptions.optional().describe('default request controls for CouchDB requests'),
     throwOnGetNotFound: z
       .boolean()
       .optional()
       .default(false)
-      .describe('if a get is 404 should we throw or return undefined'),
+      .describe('if true, get() throws NotFoundError on 404; otherwise it returns null'),
     useConsoleLogger: z
       .boolean()
       .optional()
@@ -77,5 +58,7 @@ export const CouchConfig = z
   })
   .describe('The std config object')
 
+export type CouchAuth = StandardSchemaV1.InferOutput<typeof CouchAuth>
+export type CouchAuthInput = StandardSchemaV1.InferInput<typeof CouchAuth>
 export type CouchConfig = StandardSchemaV1.InferOutput<typeof CouchConfig>
 export type CouchConfigInput = StandardSchemaV1.InferInput<typeof CouchConfig>

package/schema/request.mts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+const isAbortSignal = (value: unknown): value is AbortSignal => {
+  return value instanceof AbortSignal
+}
+
+export type Dispatcher = RequestInit['dispatcher']
+
+export type RequestOptions = {
+  dispatcher?: Dispatcher
+  signal?: AbortSignal
+  timeout?: number
+}
+
+export type RequestOptionsInput = RequestOptions
+
+const isDispatcher = (value: unknown): value is Dispatcher => {
+  if (typeof value !== 'object' || value === null) return false
+  return typeof (value as { dispatch?: unknown }).dispatch === 'function'
+}
+
+export const RequestOptions: z.ZodType<RequestOptions, RequestOptionsInput> = z.strictObject({
+  dispatcher: z
+    .custom<Dispatcher>(isDispatcher, {
+      message: 'dispatcher must expose a dispatch method'
+    })
+    .optional()
+    .describe('dispatcher to use for the request'),
+  signal: z
+    .custom<AbortSignal>(isAbortSignal, {
+      message: 'signal must be an AbortSignal'
+    })
+    .optional()
+    .describe('abort signal for the request'),
+  timeout: z.number().nonnegative().optional().describe('request timeout in milliseconds')
+})

package/schema/sugar/watch.mts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import type { StandardSchemaV1 } from '../../types/standard-schema.ts'
 
 export const WatchOptions = z
-  .object({
+  .strictObject({
     include_docs: z.boolean().default(false),
     maxRetries: z.number().describe('maximum number of retries before giving up'),
     initialDelay: z.number().describe('initial delay between retries in milliseconds'),