hide-a-bed 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+hide-a-bed
+-----------
+
+A simple way to abstract couchdb, and make your interface to the database testable. 
+
+Install
+-----
+
+There are two packages, one for runtime that contains the real implementations and schema, and the other contains the stubs for tests.
+
+```
+npm i hide-a-bed --save
+npm i hide-a-bed-stub --save-dev
+
+```
+
+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
+}
+
+```
+
+Using doStuff, in a real env, connecting to a real couch
+```
+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')
+
+```
+
+Mocking out the calls in a test, never connects to the network
+```
+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'
+
+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])
+
+    // build up a service api with all your fake endpoints
+    const services = { db, callSomeApi: callSomeApiMock }
+    const afterStuff = await doStuff(config, services, 'happy-doc-id')
+})
+
+```
+
+Below are all the couch apis available
+-------------
+
+__TODO__
+
+
+

package/impl/bulk.mjs

@@ -0,0 +1,44 @@
+// @ts-check
+import needle from 'needle'
+
+const opts = {
+  json: true,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+}
+
+export async function bulkSave (config, docs) {
+  if (!docs) return
+  if (!docs.length) return
+
+  const url = `${config.couch}/_bulk_docs`
+  const body = { docs }
+  const resp = await needle('post', url, body, opts)
+  if (resp.statusCode !== 201) throw new Error('could not save')
+  const results = resp?.body || []
+  return results
+}
+
+export async function bulkGet (config, ids) {
+  const keys = ids
+  const url = `${config.couch}/_all_docs?include_docs=true`
+  const body = { keys }
+  const resp = await needle('post', url, body, opts)
+  if (resp.statusCode !== 200) throw new Error('could not fetch')
+  const rows = resp?.body?.rows || []
+  const docs = []
+  rows.forEach(r => {
+    if (r.error) return
+    if (!r.key) return
+    if (!r.doc) return
+    docs.push(r.doc)
+  })
+  return docs
+}
+
+export async function bulkRemove (config, ids) {
+  const docs = await bulkGet(config, ids)
+  docs.forEach(d => { d._deleted = true })
+  return bulkSave(config, docs)
+}

package/impl/crud.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+import needle from 'needle'
+import { CouchGet, CouchPut } from '../schema/crud.mjs'
+
+const opts = {
+  json: true,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+}
+
+export const get = CouchGet.implement(async (config, id) => {
+  const url = `${config.couch}/${id}`
+  const resp = await needle('get', url, opts)
+  const result = resp?.body || {}
+  result.statusCode = resp.statusCode
+  if (resp.statusCode !== 200) {
+    throw new Error('not found')
+  }
+  return result
+})
+
+export const put = CouchPut.implement(async (config, doc) => {
+  const url = `${config.couch}/${doc._id}`
+  const body = doc
+  const resp = await needle('put', url, body, opts)
+  const result = resp?.body || {}
+  result.statusCode = resp.statusCode
+  if (resp.statusCode === 409) {
+    result.ok = false
+    result.error = 'conflict'
+  }
+  return result
+})

package/impl/query.mjs

@@ -0,0 +1,45 @@
+// @ts-check
+
+import { z } from 'zod' // eslint-disable-line
+import needle from 'needle'
+import { SimpleViewQuery, SimpleViewQueryResponse } from '../schema/query.mjs' // eslint-disable-line
+
+import pkg from 'lodash'
+const { includes } = pkg
+
+/** @type { z.infer<SimpleViewQuery> } query */
+export const query = SimpleViewQuery.implement(async (config, view, options) => {
+  // @ts-ignore
+  const qs = queryString(options, ['key', 'startkey', 'endkey', 'reduce', 'group', 'group_level'])
+
+  const opts = {
+    json: true,
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  }
+  const url = `${config.couch}/${view}?${qs.toString()}`
+  // @ts-ignore
+  const results = await needle('get', url, opts)
+  /** @type { z.infer<SimpleViewQueryResponse> } body */
+  const body = results.body
+  if (body.error) throw new Error(body.error)
+  return body
+})
+
+function queryString (options, params) {
+  const parts = Object.keys(options).map(key => {
+    let value = options[key]
+    if (includes(params, key)) {
+      if (typeof value === 'string') value = `"${value}"`
+      if (Array.isArray(value)) {
+        value = '[' + value.map(i => {
+          if (typeof i === 'string') return `"${i}"`
+          return i
+        }).join(',') + ']'
+      }
+    }
+    return `${key}=${value}`
+  })
+  return parts.join('&')
+}

package/index.mjs

@@ -0,0 +1,6 @@
+import { bulkGet, bulkSave, bulkRemove } from './impl/bulk'
+import { get, put } from './impl/crud'
+import { query } from './impl/query'
+
+export { bulkGet, bulkSave, bulkRemove, get, put, query }
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "hide-a-bed",
+  "version": "1.0.0",
+  "description": "An abstraction over couchdb calls that includes easy mock/stubs with pouchdb",
+  "main": "index.mjs",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanramage/hide-a-bed.git"
+  },
+  "keywords": [
+    "couchdb",
+    "test"
+  ],
+  "author": "ryan ramage",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/ryanramage/hide-a-bed/issues"
+  },
+  "homepage": "https://github.com/ryanramage/hide-a-bed#readme",
+  "dependencies": {
+    "needle": "^3.2.0",
+    "zod": "^3.22.4"
+  }
+}

package/schema/bulk.mjs

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+// TODO - type this object
+export const SaveResponseSchema = z.array(z.object({
+  ok: z.boolean().nullish(),
+  id: z.string(),
+  rev: z.string().nullish(),
+  error: z.string().nullish().describe('if an error occured, one word reason, eg conflict'),
+  reason: z.string().nullish().describe('a full error message')
+}))
+/** @typedef { z.infer<typeof SaveResponseSchema> } Response */
+
+export const BulkSave = z.function().args(
+  z.object({
+    couch: z.string().describe('the url to the couch database')
+  }).passthrough().describe('config object'),
+  z.array(z.object({
+    _id: z.string()
+  }).passthrough())
+).returns(z.promise(SaveResponseSchema))
+/** @typedef { z.infer<typeof SaveSchema> } Save */
+
+export const BulkGet = z.function().args(
+  z.object({
+    couch: z.string().describe('the url to the couch database')
+  }).passthrough().describe('config object'),
+  z.array(z.string().describe('the ids to get'))
+)

package/schema/crud.mjs

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+export const CouchDoc = z.object({
+  _id: z.string().describe('the couch doc id'),
+  _rev: z.string().optional().describe('the doc revision')
+}).passthrough()
+
+export const CouchDocResponse = z.object({
+  ok: z.boolean().optional().describe('did the request succeed'),
+  error: z.string().optional().describe('the error message, if did not succed'),
+  statusCode: z.number(),
+  id: z.string().optional().describe('the couch doc id'),
+  rev: z.string().optional().describe('the new rev of the doc')
+})
+
+export const CouchConfig = z.object({
+  couch: z.string().describe('the url of the couch db')
+}).passthrough().describe('The std config object')
+
+export const CouchPut = z.function().args(
+  CouchConfig,
+  CouchDoc
+).returns(z.promise(CouchDocResponse))
+
+export const CouchGet = z.function().args(
+  CouchConfig,
+  z.string().describe('the couch doc id')
+).returns(z.promise(CouchDoc))

package/schema/query.mjs

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+export const SimpleViewQueryResponse = z.object({
+  error: z.string().optional().describe('if something is wrong'),
+  rows: z.array(z.object({
+    id: z.string().optional(),
+    key: z.any().nullable(),
+    value: z.any().nullable(),
+    doc: z.object({}).passthrough().optional()
+  }))
+}).passthrough()
+
+export const SimpleViewQueryConfig = z.object({
+  couch: z.string().describe('the url of the couch db')
+}).passthrough().describe('The std config object')
+
+export const SimpleViewQuery = z.function().args(
+  SimpleViewQueryConfig,
+  z.string().describe('the view name'),
+  z.object({
+    startkey: z.any().optional(),
+    endkey: z.any().optional(),
+    descending: z.boolean().optional().describe('sort results descending'),
+    skip: z.number().positive().optional().describe('skip this many rows'),
+    limit: z.number().positive().optional().describe('limit the results to this many rows'),
+    key: z.any().optional(),
+    include_docs: z.boolean().optional().describe('join the id to the doc and return it'),
+    reduce: z.boolean().optional().describe('reduce the results'),
+    group: z.boolean().optional().describe('group the results'),
+    group_level: z.number().positive().optional().describe('group the results at this level')
+  }).optional().describe('query options')
+).returns(z.promise(SimpleViewQueryResponse))