hide-a-bed 4.1.2 → 5.0.0

package/README.md

@@ -36,6 +36,14 @@ const doc = db.get('doc-123')
 | [`patchDangerously()`](#patchdangerously) | [`bulkGetDictionary()`](#bulkgetdictionary) | |
 | [`getAtRev()`](#getatrev) | [`bulkSaveTransaction()`](#bulksavetransaction) | |
 
+
+Some *Sugar* API helpers
+
+ - [`createLock()`](#createLock)
+ - [`removeLock()`](#removeLock)
+ - [`changes()`](#changes)
+ - [`watchDocs()`](#watchDocs)
+
 ### Document Operations
 
 #### get
@@ -163,6 +171,52 @@ const doc = await getAtRev(config, 'doc-123', '2-fsdjfsdakljfsajlksd')
 console.log(doc._id, doc._rev)
 ```
 
+#### createLock
+
+Create a lock document to try and prevent concurrent modifications.
+
+Note this does not internally lock the document that is referenced by the id. People can still mutate it with 
+all the other document mutation functions. This should just be used at an app level to coordinate access 
+on long running document editing.
+
+**Parameters:**
+- `config`: Object with `couch` URL string
+- `docId`: Document ID string to lock
+- `options`: Lock options object:
+  - `enableLocking`: Boolean to enable/disable locking (default: true)
+  - `username`: String identifying who created the lock
+
+Returns a Promise resolving to boolean indicating if lock was created successfully.
+
+#### removeLock
+
+Remove a lock from a document.
+
+**Parameters:**
+- `config`: Object with `couch` URL string
+- `docId`: Document ID string to unlock
+- `options`: Lock options object:
+  - `enableLocking`: Boolean to enable/disable locking (default: true)
+  - `username`: String identifying who is removing the lock
+
+Only the user who created the lock can remove it.
+
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const options = {
+  enableLocking: true,
+  username: 'alice'
+}
+
+const locked = await createLock(config, 'doc-123', options)
+if (locked) {
+  // Document is now locked for exclusive access
+  // Perform your updates here
+  await removeLock(config, 'doc-123', options)
+}
+// Lock is now removed if it existed and was owned by 'alice'
+```
+
 ### Bulk Operations
 
 #### bulkSave
@@ -181,7 +235,7 @@ const docs = [
   { _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' }
 // ]
@@ -202,7 +256,7 @@ Not found documents will still have a row in the results, but the doc will be nu
 const config = { couch: 'http://localhost:5984/mydb' }
 const ids = ['doc1', 'doc2', 'doesNotExist']
 const docs = await bulkGet(config, ids)
-// docs: [
+// rows: [
 //   { _id: 'doc1', _rev: '1-abc123', type: 'user', name: 'Alice' },
 //   { _id: 'doc2', _rev: '1-def456', type: 'user', name: 'Bob' },
 //   { key: 'notThereDoc', error: 'not_found' }
@@ -500,4 +554,108 @@ Each operation logs appropriate information at these levels:
 - info: Operation start/completion
 - debug: Detailed operation information
 
+#### changes()
+
+Subscribe to the CouchDB changes feed to receive real-time updates.
+
+**Parameters:**
+- `config`: Object with `couch` URL string
+- 'onChange': function called for each change
+- `options`: Optional object with parameters:
+  - `since`: String or number indicating where to start from ('now' or update sequence number)
+  - `include_docs`: Boolean to include full documents
+  - `filter`: String name of design document filter function
+  - Other standard CouchDB changes feed parameters
+
+Returns an EventEmitter that emits 'change' events with change objects.
+
+```javascript
+const config = { couch: 'http://localhost:5984/mydb' }
+const options = { 
+  since: 'now',
+  include_docs: true
+}
+
+const onChange = change => {
+  console.log('Document changed:', change.id)
+  console.log('New revision:', change.changes[0].rev)
+  if (change.doc) {
+    console.log('Document contents:', change.doc)
+  }
+}
+const feed = await changes(config, onChange, options)
+
+
+// Stop listening to changes
+feed.stop()
+```
+
+The changes feed is useful for:
+- Building real-time applications
+- Keeping local data in sync with CouchDB
+- Triggering actions when documents change
+- Implementing replication
+
+
+#### watchDocs()
+
+Watch specific documents for changes in real-time.
+
+ **Parameters:**
+ - `config`: Object with `couch` URL string
+ - `docIds`: String or array of document IDs to watch (max 100
+ - `onChange`: Function called for each change
+ - `options`: Optional object with parameters:
+   - `include_docs`: Boolean to include full documents (defaul
+ false)
+   - `maxRetries`: Maximum reconnection attempts (default: 10)
+   - `initialDelay`: Initial reconnection delay in ms (default
+ 1000)
+   - `maxDelay`: Maximum reconnection delay in ms (default:
+ 30000)
+
+ Returns an EventEmitter that emits:
+ - 'change' events with change objects
+ - 'error' events when max retries reached
+ - 'end' events with last sequence number
+
+ ```javascript
+ const config = { couch: 'http://localhost:5984/mydb' }
+
+ // Watch a single document
+ const feed = await watchDocs(config, 'doc123', change => {
+   console.log('Document changed:', change.id)
+   console.log('New revision:', change.changes[0].rev)
+ })
+
+ // Watch multiple documents with full doc content
+ const feed = await watchDocs(
+   config,
+   ['doc1', 'doc2', 'doc3'],
+   change => {
+     if (change.doc) {
+       console.log('Updated document:', change.doc)
+     }
+   },
+   { include_docs: true }
+ )
+
+ // Handle errors
+ feed.on('error', error => {
+   console.error('Watch error:', error)
+ })
+
+ // Handle end of feed
+ feed.on('end', ({ lastSeq }) => {
+   console.log('Feed ended at sequence:', lastSeq)
+ })
+
+ // Stop watching
+ feed.stop()
+ ```
+
+ The watchDocs feed is useful for:
+ - Building real-time applications focused on specific documents
+ - Triggering actions when particular documents change
+ - Maintaining cached copies of frequently accessed documents
 

package/dualmode.config.json

@@ -0,0 +1,11 @@
+{
+  "esbuild": { 
+    "entryPoints": { 
+     "ignore": [ 
+       "./node_modules/**/*",
+       "./tests/**",
+       "./temp/**"
+      ] 
+    } 
+  }
+}

package/impl/changes.mjs

@@ -0,0 +1,58 @@
+// @ts-check
+import needle from 'needle'
+import { EventEmitter } from 'events'
+import { Changes } from '../schema/changes.mjs'
+
+/** @typedef {{
+ *   seq: string|number,
+ *   id: string,
+ *   changes: Array<{rev: string}>,
+ *   deleted?: boolean,
+ *   doc?: any
+ * }} ChangeInfo */
+// @ts-ignore
+import ChangesStream from 'changes-stream'
+import { createLogger } from './logger.mjs'
+import { sleep } from './patch.mjs'
+
+const MAX_RETRY_DELAY = 30000 // 30 seconds
+
+/** @type { import('../schema/changes.mjs').ChangesSchema } */
+export const changes = Changes.implement(async (config, onChange, options = {}) => {
+  const emitter = new EventEmitter()
+  const logger = createLogger(config)
+  options.db = config.couch
+  if (options.since && options.since === 'now') {
+    const opts = {
+      json: true,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    // request the GET on config.couch and get the update_seq
+    const resp = await needle('get', config.couch, opts)
+    options.since = resp.body.update_seq
+  }
+
+  const changes = ChangesStream(options)
+
+  changes.on('readable', () => {
+    const change = changes.read();
+    if (change.results && Array.isArray(change.results)) {
+      // emit each one seperate
+      change.results.forEach((/** @type {ChangeInfo} */ c) => emitter.emit('change', c))
+    } else emitter.emit('change', change)
+  });
+
+  // Bind the provided change listener
+  emitter.on('change', onChange)
+
+  return {
+    on: (event, listener) => emitter.on(event, listener),
+    removeListener: (event, listener) => emitter.removeListener(event, listener),
+    stop: () => {
+      changes.destroy()
+      emitter.removeAllListeners()
+    }
+  }
+})

package/impl/query.mjs

@@ -9,28 +9,53 @@ import { createLogger } from './logger.mjs'
 import pkg from 'lodash'
 const { includes } = pkg
 
-/** @type { z.infer<SimpleViewQuery> } query */
-export const query = SimpleViewQuery.implement(async (config, view, options) => {
+/**
+ * @type { z.infer<SimpleViewQuery> }
+ * @param {import('../schema/config.mjs').CouchConfigSchema} config
+ * @param {string} view
+ * @param {import('../schema/query.mjs').SimpleViewOptionsSchema} [options]
+ */
+export const query = SimpleViewQuery.implement(async (config, view, options = {}) => {
   const logger = createLogger(config)
   logger.info(`Starting view query: ${view}`)
   logger.debug('Query options:', options)
 
   // @ts-ignore
-  const qs = queryString(options, ['key', 'startkey', 'endkey', 'reduce', 'group', 'group_level', 'stale', 'limit'])
+  let qs = queryString(options, ['key', 'startkey', 'endkey', 'reduce', 'group', 'group_level', 'stale', 'limit'])
   logger.debug('Generated query string:', qs)
-
+  let method = 'GET'
+  let payload = null
   const opts = {
     json: true,
     headers: {
       'Content-Type': 'application/json'
     }
   }
+
+  // If keys are supplied, issue a POST to circumvent GET query string limits
+  // see http://wiki.apache.org/couchdb/HTTP_view_API#Querying_Options
+  if (typeof options.keys !== 'undefined') {
+    const MAX_URL_LENGTH = 2000;
+    // according to http://stackoverflow.com/a/417184/680742,
+    // the de facto URL length limit is 2000 characters
+
+    const keysAsString = `keys=${encodeURIComponent(JSON.stringify(options.keys))}`;
+    if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) {
+      // If the keys are short enough, do a GET. we do this to work around
+      // Safari not understanding 304s on POSTs (see pouchdb/pouchdb#1239)
+      qs += (qs[0] === '?' ? '&' : '?') + keysAsString;
+    } else {
+      method = 'POST';
+      payload = {keys: options.keys};
+    }
+  }
+
   const url = `${config.couch}/${view}?${qs.toString()}`
   // @ts-ignore
   let results
   try {
-    logger.debug(`Sending GET request to: ${url}`)
-    results = await needle('get', url, opts)
+    logger.debug(`Sending ${method} request to: ${url}`)
+    results = (method === 'GET') ? await needle('get', url, opts) : await needle('post', url, payload, opts)
   } catch (err) {
     logger.error('Network error during query:', err)
     RetryableError.handleNetworkError(err)
@@ -63,7 +88,12 @@ export const query = SimpleViewQuery.implement(async (config, view, options) =>
  * @param {{ [key: string]: any }} options - The options object containing query parameters.
  * @param {string[]} params - The list of parameter names to include in the query string.
  */
-export function queryString (options, params) {
+/**
+ * @param {{ [key: string]: any }} options
+ * @param {string[]} params
+ * @returns {string}
+ */
+export function queryString (options = {}, params) {
   const parts = Object.keys(options).map(key => {
     let value = options[key]
     if (includes(params, key)) {

package/impl/stream.mjs

@@ -16,8 +16,25 @@ export const queryStream = (rawConfig, view, options, onRow) => new Promise((res
 
   if (!options) options = {}
 
-  const qs = queryString(options, ['key', 'startkey', 'endkey', 'reduce', 'group', 'group_level', 'stale', 'limit'])
+  let method = 'GET'
+  let payload = null
+  let qs = queryString(options, ['key', 'startkey', 'endkey', 'reduce', 'group', 'group_level', 'stale', 'limit'])
   logger.debug('Generated query string:', qs)
+
+  // If keys are supplied, issue a POST to circumvent GET query string limits
+  if (typeof options.keys !== 'undefined') {
+    const MAX_URL_LENGTH = 2000
+    const keysAsString = `keys=${encodeURIComponent(JSON.stringify(options.keys))}`
+    
+    if (keysAsString.length + qs.length + 1 <= MAX_URL_LENGTH) {
+      // If the keys are short enough, do a GET
+      qs += (qs[0] === '?' ? '&' : '?') + keysAsString
+    } else {
+      method = 'POST'
+      payload = { keys: options.keys }
+    }
+  }
+
   const url = `${config.couch}/${view}?${qs.toString()}`
   const opts = {
     json: true,
@@ -53,7 +70,9 @@ export const queryStream = (rawConfig, view, options, onRow) => new Promise((res
     resolve(undefined) // all work should be done in the stream
   })
 
-  const req = needle.get(url, opts)
+  const req = method === 'GET' 
+    ? needle.get(url, opts)
+    : needle.post(url, payload, opts)
 
   req.on('response', response => {
     logger.debug(`Received response with status code: ${response.statusCode}`)

package/impl/sugar/lock.mjs

@@ -0,0 +1,70 @@
+import { CreateLock, RemoveLock } from '../../schema/sugar/lock.mjs'
+import { put, get } from '../crud.mjs'
+import { createLogger } from '../logger.mjs'
+
+/** @type {import('../../schema/sugar/lock.mjs').CreateLockSchema} */
+export const createLock = CreateLock.implement(async (config, docId, options) => {
+  const logger = createLogger(config)
+  
+  if (!options.enableLocking) {
+    logger.debug('Locking disabled, returning true')
+    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 (error.status === 409) {
+      logger.warn(`Lock conflict for ${docId} - already locked`)
+    } else {
+      logger.error(`Error creating lock for ${docId}:`, error)
+    }
+    return false
+  }
+})
+
+/** @type {import('../../schema/sugar/lock.mjs').RemoveLockSchema} */
+export const removeLock = RemoveLock.implement(async (config, docId, options) => {
+  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/watch.mjs

@@ -0,0 +1,154 @@
+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 = {}) => {
+  const logger = createLogger(config)
+  const emitter = new EventEmitter()
+  let lastSeq = null || 'now'
+  let stopping = false
+  let retryCount = 0
+  let currentRequest = null
+  const maxRetries = options.maxRetries || 10
+  const initialDelay = options.initialDelay || 1000
+  const maxDelay = options.maxDelay || 30000
+
+  const _docIds = Array.isArray(docIds) ? docIds : [docIds]
+  if (_docIds.length === 0) throw new Error('docIds must be a non-empty array')
+  if (_docIds.length > 100) throw new Error('docIds must be an array of 100 or fewer elements')
+
+  const connect = async () => {
+    if (stopping) return
+
+    const feed = 'continuous'
+    const includeDocs = options.include_docs ?? false
+    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' },
+      parse_response: false
+    }
+
+    let buffer = ''
+    currentRequest = needle.get(url, opts)
+
+  currentRequest.on('data', chunk => {
+    buffer += chunk.toString()
+    const lines = buffer.split('\n')
+    
+    // Keep the last partial line in the buffer
+    buffer = lines.pop() || ''
+
+    // Process complete lines
+    for (const line of lines) {
+      if (line.trim()) {
+        try {
+          const change = JSON.parse(line)
+          if (!change.id) return null // ignore just last_seq
+          logger.debug(`Change detected, watching [${_docIds}]`, change)
+          lastSeq = change.seq || change.last_seq
+          emitter.emit('change', change)
+        } catch (err) {
+          logger.error('Error parsing change:', err, 'Line:', line)
+        }
+      }
+    }
+  })
+
+  currentRequest.on('response', response => {
+    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()
+      handleReconnect()
+    } else {
+      // Reset retry count on successful connection
+      retryCount = 0
+    }
+  })
+
+  currentRequest.on('error', async err => {
+    if (stopping) {
+      logger.info('stopping in progress, ignore stream error')
+      return
+    }
+    logger.error(`Network error during stream, watching [${_docIds}]:`, err.toString())
+    try {
+      RetryableError.handleNetworkError(err)
+    } catch (filteredError) {
+      if (filteredError instanceof RetryableError) {
+        logger.info(`Retryable error, watching [${_docIds}]:`, filteredError.toString())
+        handleReconnect()
+      } else {
+        logger.error(`Non-retryable error, watching [${_docIds}]`, nonRetryErr)
+        emitter.emit('error', nonRetryErr)
+      }
+    }
+  })
+
+  currentRequest.on('end', () => {
+    // Process any remaining data in buffer
+    if (buffer.trim()) {
+      try {
+        const change = JSON.parse(buffer)
+        logger.debug('Final change detected:', change)
+        emitter.emit('change', change)
+      } catch (err) {
+        logger.error('Error parsing final change:', err)
+      }
+    }
+    logger.info('Stream completed. Last seen seq: ', lastSeq)
+    emitter.emit('end', { lastSeq })
+    
+    // If the stream ends and we're not stopping, attempt to reconnect
+    if (!stopping) {
+      handleReconnect()
+    }
+  })
+  }
+
+  const handleReconnect = async () => {
+    if (stopping || retryCount >= maxRetries) {
+      if (retryCount >= maxRetries) {
+        logger.error(`Max retries (${maxRetries}) reached, giving up`)
+        emitter.emit('error', new Error('Max retries reached'))
+      }
+      return
+    }
+
+    const delay = Math.min(initialDelay * Math.pow(2, retryCount), maxDelay)
+    retryCount++
+    
+    logger.info(`Attempting to reconnect in ${delay}ms (attempt ${retryCount} of ${maxRetries})`)
+    await sleep(delay)
+    
+    try {
+      connect()
+    } catch (err) {
+      logger.error('Error during reconnection:', err)
+      handleReconnect()
+    }
+  }
+
+  // Start initial connection
+  connect()
+
+  // Bind the provided change listener
+  emitter.on('change', onChange)
+
+  return {
+    on: (event, listener) => emitter.on(event, listener),
+    removeListener: (event, listener) => emitter.removeListener(event, listener),
+    stop: () => {
+      stopping = true
+      if (currentRequest) currentRequest.abort()
+      emitter.emit('end', { lastSeq })
+      emitter.removeAllListeners()
+    }
+  }
+})

package/index.mjs

@@ -1,7 +1,10 @@
 // @ts-check */
 import { bulkGet, bulkSave, bulkRemove, bulkGetDictionary, bulkSaveTransaction } from './impl/bulk.mjs'
 import { get, put, getAtRev } from './impl/crud.mjs'
+import { changes } from './impl/changes.mjs'
 import { patch, patchDangerously } from './impl/patch.mjs'
+import { createLock, removeLock } from './impl/sugar/lock.mjs'
+import { watchDocs } from './impl/sugar/watch.mjs'
 import { query } from './impl/query.mjs'
 import { queryStream } from './impl/stream.mjs'
 import { createQuery } from './impl/queryBuilder.mjs'
@@ -9,8 +12,11 @@ import { withRetry } from './impl/retry.mjs'
 import { BulkSave, BulkGet, BulkRemove, BulkGetDictionary, BulkSaveTransaction } from './schema/bulk.mjs'
 import { CouchConfig } from './schema/config.mjs'
 import { SimpleViewQuery, SimpleViewQueryResponse } from './schema/query.mjs'
+import { Changes, ChangesOptions, ChangesResponse } from './schema/changes.mjs'
 import { SimpleViewQueryStream, OnRow } from './schema/stream.mjs'
 import { Patch, PatchDangerously } from './schema/patch.mjs'
+import { Lock, LockOptions, CreateLock, RemoveLock } from './schema/sugar/lock.mjs'
+import { WatchDocs } from './schema/sugar/watch.mjs'
 import { CouchDoc, CouchDocResponse, CouchPut, CouchGet, CouchGetAtRev } from './schema/crud.mjs'
 import { Bind } from './schema/bind.mjs'
 
@@ -32,7 +38,15 @@ const schema = {
   Patch,
   PatchDangerously,
   CouchGetAtRev,
-  Bind
+  Bind,
+  Lock,
+  WatchDocs,
+  LockOptions,
+  CreateLock,
+  RemoveLock,
+  Changes,
+  ChangesOptions,
+  ChangesResponse
 }
 
 /** @type { import('./schema/bind.mjs').BindSchema } */
@@ -60,7 +74,11 @@ const bindConfig = Bind.implement((
     patchDangerously: patchDangerously.bind(null, config), // patchDangerously not included in retry
     bulkRemove: config.bindWithRetry ? withRetry(bulkRemove.bind(null, config), retryOptions) : bulkRemove.bind(null, config),
     bulkGetDictionary: config.bindWithRetry ? withRetry(bulkGetDictionary.bind(null, config), retryOptions) : bulkGetDictionary.bind(null, config),
-    bulkSaveTransaction: bulkSaveTransaction.bind(null, config)
+    bulkSaveTransaction: bulkSaveTransaction.bind(null, config),
+    createLock: createLock.bind(null, config),
+    removeLock: removeLock.bind(null, config),
+    watchDocs: watchDocs.bind(null, config),
+    changes: changes.bind(null, config)
   }
 })
 
@@ -83,5 +101,7 @@ export {
 
   bindConfig,
   withRetry,
-  createQuery
+  createQuery,
+  createLock,
+  removeLock
 }