hide-a-bed 1.2.0 → 2.1.0

package/README.md

@@ -1,73 +1,168 @@
-hide-a-bed
------------
-
-A simple way to abstract couchdb, and make your interface to the database testable. 
+API 
+-------------
 
-Install
------
+### Document Operations
 
-There are two packages, one for runtime that contains the real implementations and schema, and the other contains the stubs for tests.
+#### get(config, id)
+Get a single document by ID.
+- `config`: Object with `couch` URL string
+- `id`: Document ID string
+- Returns: Promise resolving to document object or null if not found
 
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const doc = await get(config, 'doc-123')
+if (doc) {
+  console.log(doc._id, doc._rev)
+}
 ```
-npm i hide-a-bed --save
-npm i hide-a-bed-stub --save-dev
 
-```
+#### put(config, doc) 
+Save a document.
+- `config`: Object with `couch` URL string
+- `doc`: Document object with `_id` property
+- Returns: Promise resolving to response with `ok`, `id`, `rev` properties
 
-Code that uses some example db apis
-```
-export function doStuff (config, services, id) {
-  const doc = await services.db.get(config, id)
-  const apiResult = services.callSomeApi(config, doc.userName)
-  const query = {
-    startkey: apiResult.startTime,
-    endkey: apiResult.endTime
-  }
-  const queryResults = await db.query(config, '_design/userThings/_view/byTime', query)
-  return queryResults.rows
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const doc = { 
+  _id: 'doc-123',
+  type: 'user',
+  name: 'Alice'
 }
-
+const result = await put(config, doc)
+// result: { ok: true, id: 'doc-123', rev: '1-abc123' }
 ```
 
-Using doStuff, in a real env, connecting to a real couch
+#### patch(config, id, properties)
+Update specific properties of a document with retry mechanism.
+- `config`: Object with:
+  - `couch`: URL string
+  - `retries`: Optional number of retry attempts (default: 5)
+  - `delay`: Optional milliseconds between retries (default: 1000)
+- `id`: Document ID string
+- `properties`: Object with properties to update
+- Returns: Promise resolving to response with `ok`, `id`, `rev` properties
+
+```javascript
+const config = { 
+  couch: 'http://localhost:5984/mydb',
+  retries: 3,
+  delay: 500
+}
+const properties = { 
+  name: 'Alice Smith',
+  updated: true
+}
+const result = await patch(config, 'doc-123', properties)
+// result: { ok: true, id: 'doc-123', rev: '2-xyz789' }
 ```
-import db from 'hide-a-bed'
-import { doStuff } from './doStuff'
-import { callSomeApi } from './api'
-// the config object needs a couch url
-const config = { couch: 'http://localhost:5984/mydb' }
-// build up a service api for all your external calls that can be mocked/stubbed
-const services = { db, callSomeApi }
-const afterStuff = await doStuff(config, services, 'happy-doc-id')
 
-```
+#### remove(config, id)
+Delete a document by ID.
+- `config`: Object with `couch` URL string
+- `id`: Document ID string to delete
+- Returns: Promise resolving to response with `ok` and `rev` properties
 
-Mocking out the calls in a test, never connects to the network
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const result = await remove(config, 'doc-123')
+// result: { ok: true, id: 'doc-123', rev: '2-def456' }
 ```
-import { setup } from 'hide-a-bed-stub' // different package, since installed with --save-dev reduces space
-import { doStuff } from './doStuff'
-import { callSomeApiMock } from './test/mock/api'
-// the config object needs a couch url, prove to yourself that its mocked with a fakeurl
-const config = { couch: 'http://fakeurl:5984/mydb' }
 
-// we import or design docs that we will need for the db
-import userThingsDesignDoc from './ddocs/userThingsDDoc.js'
+### Bulk Operations
+
+#### bulkSave(config, docs)
+Save multiple documents in one request.
+- `config`: Object with `couch` URL string
+- `docs`: Array of document objects, each with `_id`
+- Returns: Promise resolving to array of results with `ok`, `id`, `rev` for each doc
 
-test('doStuff works in stub mode', async t => {
-    // we have to setup the db with the design docs that are required
-    const db = await setup([userThingsDesignDoc])
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const docs = [
+  { _id: 'doc1', type: 'user', name: 'Alice' },
+  { _id: 'doc2', type: 'user', name: 'Bob' }
+]
+const results = await bulkSave(config, docs)
+// results: [
+//   { ok: true, id: 'doc1', rev: '1-abc123' },
+//   { ok: true, id: 'doc2', rev: '1-def456' }
+// ]
+```
 
-    // build up a service api with all your fake endpoints
-    const services = { db, callSomeApi: callSomeApiMock }
-    const afterStuff = await doStuff(config, services, 'happy-doc-id')
-})
+#### bulkGet(config, ids)
+Get multiple documents by ID.
+- `config`: Object with `couch` URL string
+- `ids`: Array of document ID strings
+- Returns: Promise resolving to array of documents
 
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const ids = ['doc1', 'doc2']
+const docs = await bulkGet(config, ids)
+// docs: [
+//   { _id: 'doc1', _rev: '1-abc123', type: 'user', name: 'Alice' },
+//   { _id: 'doc2', _rev: '1-def456', type: 'user', name: 'Bob' }
+// ]
 ```
 
-Below are all the couch apis available
--------------
+#### bulkRemove(config, ids)
+Delete multiple documents in one request.
+- `config`: Object with `couch` URL string
+- `ids`: Array of document ID strings to delete
+- Returns: Promise resolving to array of results with `ok`, `id`, `rev` for each deletion
 
-__TODO__
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const ids = ['doc1', 'doc2']
+const results = await bulkRemove(config, ids)
+// results: [
+//   { ok: true, id: 'doc1', rev: '2-ghi789' },
+//   { ok: true, id: 'doc2', rev: '2-jkl012' }
+// ]
+```
 
+### View Queries
+
+#### query(config, view, options)
+Query a view with options.
+- `config`: Object with `couch` URL string
+- `view`: View path string (e.g. '_design/doc/_view/name')
+- `options`: Optional object with query parameters:
+  - `startkey`: Start key for range
+  - `endkey`: End key for range
+  - `key`: Exact key match
+  - `descending`: Boolean to reverse sort
+  - `skip`: Number of results to skip
+  - `limit`: Max number of results
+  - `include_docs`: Boolean to include full docs
+  - `reduce`: Boolean to reduce results
+  - `group`: Boolean to group results
+  - `group_level`: Number for group level
+- Returns: Promise resolving to response with `rows` array
+
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const view = '_design/users/_view/by_name'
+const options = {
+  startkey: 'A',
+  endkey: 'B',
+  include_docs: true,
+  limit: 10
+}
+const result = await query(config, view, options)
+// result: {
+//   rows: [
+//     { 
+//       id: 'doc1',
+//       key: 'Alice',
+//       value: 1,
+//       doc: { _id: 'doc1', name: 'Alice', type: 'user' }
+//     },
+//     // ... more rows
+//   ]
+// }
+```
 
 

package/impl/crud.mjs

@@ -12,11 +12,9 @@ const opts = {
 export const get = CouchGet.implement(async (config, id) => {
   const url = `${config.couch}/${id}`
   const resp = await needle('get', url, opts)
+  if (resp.statusCode === 404) return null
   const result = resp?.body || {}
-  result.statusCode = resp.statusCode
-  if (resp.statusCode !== 200) {
-    throw new Error('not found')
-  }
+  if (resp.statusCode !== 200) { throw new Error(result.reason || 'failed') }
   return result
 })
 

package/impl/patch.mjs

@@ -0,0 +1,36 @@
+import { get, put } from './crud.mjs'
+import { CouchPatch } from '../schema/patch.mjs'
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+export const patch = CouchPatch.implement(async (config, id, properties) => {
+  const maxRetries = config.retries || 5
+  const delay = config.delay || 1000
+  let attempts = 0
+
+  while (attempts <= maxRetries) {
+    try {
+      const doc = await get(config, id)
+      const updatedDoc = { ...doc, ...properties }
+      const result = await put(config, updatedDoc)
+      
+      // Check if the response indicates a conflict
+      if (result.ok) {
+        return result
+      }
+      // If not ok, treat as conflict and retry
+      attempts++
+      if (attempts > maxRetries) {
+        throw new Error(`Failed to patch after ${maxRetries} attempts`)
+      }
+      await sleep(delay)
+    } catch (err) {
+      // Handle other errors (network, etc)
+      attempts++
+      if (attempts > maxRetries) {
+        throw new Error(`Failed to patch after ${maxRetries} attempts: ${err.message}`)
+      }
+      await sleep(delay)
+    }
+  }
+})

package/index.mjs

@@ -1,10 +1,12 @@
 import { bulkGet, bulkSave, bulkRemove } from './impl/bulk.mjs'
 import { get, put } from './impl/crud.mjs'
+import { patch } from './impl/patch.mjs'
 import { query } from './impl/query.mjs'
 import { queryStream } from './impl/stream.mjs'
 import { BulkSave, BulkGet } from './schema/bulk.mjs'
 import { CouchConfig } from './schema/config.mjs'
 import { SimpleViewQuery, SimpleViewQueryResponse } from './schema/query.mjs'
+import { PatchConfig, PatchDoc } from './schema/patch.mjs'
 import { CouchDoc, CouchDocResponse, CouchPut, CouchGet } from './schema/crud.mjs'
 
 const schema = {
@@ -16,8 +18,10 @@ const schema = {
   CouchGet,
   CouchPut,
   CouchDoc,
-  CouchDocResponse
+  CouchDocResponse,
+  PatchConfig,
+  PatchDoc
 }
 
-export { get, put, bulkGet, bulkSave, bulkRemove, query, queryStream, schema }
+export { get, put, patch, bulkGet, bulkSave, bulkRemove, query, queryStream, schema }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hide-a-bed",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "An abstraction over couchdb calls that includes easy mock/stubs with pouchdb",
   "main": "index.mjs",
   "scripts": {

package/schema/bulk.mjs

@@ -22,3 +22,8 @@ export const BulkGet = z.function().args(
   CouchConfig,
   z.array(z.string().describe('the ids to get'))
 )
+
+export const BulkRemove = z.function().args(
+  CouchConfig,
+  z.array(z.string().describe('the ids to delete'))
+).returns(z.promise(BulkSaveResponseSchema))

package/schema/crud.mjs

@@ -22,4 +22,4 @@ export const CouchPut = z.function().args(
 export const CouchGet = z.function().args(
   CouchConfig,
   z.string().describe('the couch doc id')
-).returns(z.promise(CouchDoc))
+).returns(z.promise(CouchDoc.nullable()))

package/schema/patch.mjs

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+import { CouchConfig } from './config.mjs'
+import { CouchDocResponse } from './crud.mjs'
+
+export const PatchConfig = CouchConfig.extend({
+  retries: z.number().min(0).max(100).optional(),
+  delay: z.number().min(0).optional()
+})
+
+export const PatchProperties = z.record(z.string(), z.any())
+
+export const CouchPatch = z.function()
+  .args(
+    PatchConfig,
+    z.string().describe('the couch doc id'),
+    PatchProperties
+  )
+  .returns(z.promise(CouchDocResponse))