@eldoy/webdb 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2025 Vidar Eldøy
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# WebDB
+
+Document database API backed by CouchDB, exposed through a Mongo-style client.
+
+### Installation
+```sh
+npm i @eldoy/webdb
+````
+
+### Usage
+
+```js
+var webdb = require('@eldoy/webdb')
+var db = webdb('http://admin:mysecretpassword@localhost:5984')
+
+// Create one
+var doc = await db('user').create({ name: 'Heimdal' })
+
+// Bulk insert
+var n = await db('user').bulk([
+  { name: 'A' },
+  { name: 'B' }
+])
+
+// Update one or many
+var n = await db('user').update(
+  { name: 'A' },
+  { active: true }
+)
+
+// Get one (first match)
+var doc = await db('user').get({ name: 'Heimdal' })
+
+// Create indexes
+await db('user').index([
+  ['name'],
+  ['name', 'email']
+])
+
+// Find
+var docs = await db('user').find({ name: 'Heimdal' })
+
+// Find with sort
+var docs = await db('user').find(
+  { name: 'Heimdal' },
+  { sort: [{ name: 'asc' }] }
+)
+
+// Find with limit
+var docs = await db('user').find(
+  { name: 'Heimdal' },
+  { limit: 1 }
+)
+
+// Find with projection
+var docs = await db('user').find(
+  { name: 'Heimdal' },
+  { fields: ['name', 'email'] }
+)
+
+// Delete one or many
+var n = await db('user').delete({ active: false })
+
+// Count
+var n = await db('user').count({ name: 'Heimdal' })
+
+// Batch processing (streamed pagination)
+await db('user').batch(
+  { active: true },
+  { size: 500, sort: [{ created: 'asc' }] },
+  async function (docs) {
+    // handle a chunk
+  }
+)
+
+// Drop a specific database
+await db('user').drop()
+
+// Server-level compact
+await db.compact('user')
+
+// Drop all databases
+await db.drop()
+```
+
+### Notes on Indexing, Sorting, and Mango Queries
+
+**1. Selector fields and indexes**
+
+Mango performs best when the selector matches an existing index.
+Any field used in `{ selector: … }` benefits from being part of an index, but it is not required unless sorting is used.
+
+**2. Sorting requires indexing**
+
+Mango enforces that **every field in the sort must be indexed**.
+Example:
+
+```js
+await db('user').index([['age']])
+await db('user').find({}, { sort: [{ age: 'asc' }] })   // valid
+```
+
+Sorting without the correct index returns an error.
+
+**3. Compound indexes**
+
+An index like:
+
+```js
+await db('user').index([['name', 'email']])
+```
+
+supports selectors and sorts that use `name`, or `name` and `email` together, in the defined order.
+
+**4. Projection (`fields`)**
+
+Projection returns only selected fields.
+Unindexed projection works fine; indexing does not affect `fields`.
+
+**5. Pagination (batch)**
+
+`batch()` uses Mango bookmarks internally.
+It respects all options: `sort`, `limit`, `fields`, and `size`.
+
+**6. Create-on-first-use**
+
+Databases are auto-created when used. Explicit `drop()` allows clean-state tests.
+
+**7. Null results**
+
+`get()` returns `null` when no match exists.
+
+### ID note
+
+CouchDB stores documents with `_id`, but write responses return the same value as `id`.
+Use `doc.id` after `create()`, and `_id` for all queries and stored documents.
+
+### Acknowledgements
+
+Created by [Tekki AS](https://tekki.no)
+
+ISC Licensed.

package/index.js

@@ -0,0 +1,205 @@
+var nano = require('nano')
+
+module.exports = function (url) {
+  var server = nano(url)
+
+  var db = function (name) {
+    return api(name, server)
+  }
+
+  //
+  // SERVER-LEVEL OPS (drop all, compact specific)
+  //
+
+  db.drop = async function () {
+    var list = await server.db.list()
+    for (var i = 0; i < list.length; i++) {
+      await server.db.destroy(list[i])
+    }
+  }
+
+  db.compact = async function (name) {
+    await server.db.compact(name)
+  }
+
+  return db
+}
+
+//
+// COLLECTION-LEVEL API (ordered to match test suite)
+//
+
+function api(name, server) {
+  return {
+    //
+    // CRUD
+    //
+
+    create: async function (doc) {
+      var db = await ensure(name, server)
+      return db.insert(doc)
+    },
+
+    bulk: async function (docs) {
+      var db = await ensure(name, server)
+      await db.bulk({ docs: docs })
+      return docs.length
+    },
+
+    update: async function (query, update) {
+      var db = await ensure(name, server)
+      var r = await db.find({ selector: query })
+      if (!r.docs.length) return 0
+
+      var out = []
+      for (var i = 0; i < r.docs.length; i++) {
+        var cur = r.docs[i]
+        var next = {}
+        for (var k in cur) next[k] = cur[k]
+        for (var k in update) next[k] = update[k]
+        out.push(next)
+      }
+
+      await db.bulk({ docs: out })
+      return out.length
+    },
+
+    get: async function (query) {
+      var dbi = await ensure(name, server)
+      var r = await dbi.find({ selector: query, limit: 1 })
+      return r.docs[0] || null
+    },
+
+    //
+    // FIND
+    //
+
+    find: async function (selector, opts) {
+      var dbi = await ensure(name, server)
+
+      var q = { selector: selector }
+      if (opts) {
+        if (opts.sort) q.sort = opts.sort
+        if (opts.limit) q.limit = opts.limit
+        if (opts.fields) q.fields = opts.fields
+      }
+
+      var r = await dbi.find(q)
+      return r.docs
+    },
+
+    //
+    // INDEX
+    //
+
+    index: async function (list) {
+      var dbi = await ensure(name, server)
+      for (var i = 0; i < list.length; i++) {
+        await dbi.createIndex({ index: { fields: list[i] } })
+      }
+    },
+
+    //
+    // DELETE
+    //
+
+    delete: async function (query) {
+      var dbi = await ensure(name, server)
+
+      var r = await dbi.find({ selector: query })
+      if (!r.docs.length) return 0
+
+      var out = []
+      for (var i = 0; i < r.docs.length; i++) {
+        var d = r.docs[i]
+        out.push({
+          _id: d._id,
+          _rev: d._rev,
+          _deleted: true
+        })
+      }
+
+      await dbi.bulk({ docs: out })
+      return out.length
+    },
+
+    //
+    // COUNT
+    //
+
+    count: async function (query) {
+      var dbi = await ensure(name, server)
+      var r = await dbi.find({ selector: query })
+      return r.docs.length
+    },
+
+    //
+    // DROP (collection-level)
+    //
+
+    drop: async function () {
+      try {
+        await server.db.destroy(name)
+      } catch (e) {}
+    },
+
+    //
+    // BATCH
+    //
+
+    batch: async function (query, opt, fn) {
+      var dbi = await ensure(name, server)
+
+      var size = opt && opt.size ? opt.size : 100
+      var limit = opt && opt.limit
+      var sort = opt && opt.sort
+      var fields = opt && opt.fields
+
+      var bookmark = null
+      var remaining = limit
+
+      for (;;) {
+        var effectiveSize = size
+        if (remaining && remaining < effectiveSize) {
+          effectiveSize = remaining
+        }
+
+        var q = {
+          selector: query,
+          limit: effectiveSize
+        }
+
+        if (sort) q.sort = sort
+        if (fields) q.fields = fields
+        if (bookmark) q.bookmark = bookmark
+
+        var r = await dbi.find(q)
+        var docs = r.docs
+        if (!docs.length) break
+
+        await fn(docs)
+
+        if (remaining) {
+          remaining -= docs.length
+          if (remaining <= 0) break
+        }
+
+        if (!r.bookmark || docs.length < effectiveSize) break
+        bookmark = r.bookmark
+      }
+    }
+  }
+}
+
+//
+// ENSURE DB EXISTS
+//
+
+async function ensure(name, server) {
+  try {
+    await server.db.get(name)
+  } catch (e) {
+    await server.db.create(name)
+  }
+  return server.db.use(name)
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@eldoy/webdb",
+  "version": "0.1.0",
+  "description": "Document database client powered by CouchDB.",
+  "keywords": [
+    "database",
+    "couchdb",
+    "mango",
+    "document-store",
+    "nosql",
+    "json",
+    "client",
+    "db",
+    "nano",
+    "webdb"
+  ],
+  "scripts": {
+    "test": "spekk",
+    "test:watch": "nodemon --exec spekk"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eldoy/webdb.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eldoy/webdb/issues"
+  },
+  "homepage": "https://github.com/eldoy/webdb#readme",
+  "author": "Vidar Eldøy <vidar@eldoy.com>",
+  "license": "ISC",
+  "dependencies": {
+    "nano": "^11.0.3"
+  },
+  "devDependencies": {
+    "spekk": "^0.3.2"
+  }
+}

package/spec/tests/spekk.js

@@ -0,0 +1,7 @@
+module.exports = async function () {
+  async function setup() {}
+
+  async function teardown() {}
+
+  return { db, setup, teardown }
+}

package/spec/tests/webdb.test.js

@@ -0,0 +1,242 @@
+var webdb = require('../../index.js')
+var db = webdb('http://admin:mysecretpassword@localhost:5984')
+
+beforeEach(async function ({ t }) {
+  await db.drop()
+})
+
+//
+// CRUD: create, bulk, update, get
+//
+
+test('create', async function ({ t }) {
+  var doc = await db('user').create({ name: 'Heimdal' })
+  t.ok(doc && doc.id)
+})
+
+test('bulk', async function ({ t }) {
+  var n = await db('user').bulk([{ name: 'A' }, { name: 'B' }])
+  t.equal(n, 2)
+})
+
+test('update one', async function ({ t }) {
+  var doc = await db('user').create({ name: 'Old' })
+  var n = await db('user').update({ _id: doc.id }, { name: 'New' })
+  t.equal(n, 1)
+})
+
+test('update many', async function ({ t }) {
+  await db('user').bulk([{ role: 'x' }, { role: 'x' }, { role: 'y' }])
+  var n = await db('user').update({ role: 'x' }, { role: 'z' })
+  t.equal(n, 2)
+})
+
+test('get', async function ({ t }) {
+  await db('user').create({ name: 'Heimdal' })
+  var doc = await db('user').get({ name: 'Heimdal' })
+  t.ok(doc && doc._id)
+})
+
+//
+// FIND: base, sort, limit, fields
+//
+
+test('find', async function ({ t }) {
+  await db('user').bulk([
+    { name: 'A', age: 1 },
+    { name: 'A', age: 2 },
+    { name: 'B', age: 3 }
+  ])
+
+  var docs = await db('user').find({ name: 'A' })
+  t.ok(Array.isArray(docs))
+  t.equal(docs.length, 2)
+})
+
+test('find sort', async function ({ t }) {
+  await db('user').index([['n']])
+
+  await db('user').bulk([
+    { name: 'A', n: 3 },
+    { name: 'A', n: 1 },
+    { name: 'A', n: 2 }
+  ])
+
+  var docs = await db('user').find({ name: 'A' }, { sort: [{ n: 'asc' }] })
+  t.equal(docs[0].n, 1)
+  t.equal(docs[2].n, 3)
+})
+
+test('find limit', async function ({ t }) {
+  await db('user').bulk([{ name: 'A' }, { name: 'A' }, { name: 'A' }])
+  var docs = await db('user').find({ name: 'A' }, { limit: 1 })
+  t.equal(docs.length, 1)
+})
+
+test('find fields', async function ({ t }) {
+  await db('user').bulk([{ name: 'A', age: 10 }])
+  var docs = await db('user').find({ name: 'A' }, { fields: ['name'] })
+  t.ok(docs[0].name)
+  t.equal(docs[0].age, undefined)
+})
+
+//
+// INDEX
+//
+
+test('index', async function ({ t }) {
+  await db('user').index([['name', 'email']])
+  var docs = await db('user').find(
+    { name: 'X' },
+    { sort: [{ name: 'asc' }, { email: 'asc' }] }
+  )
+  t.ok(Array.isArray(docs))
+})
+
+//
+// DELETE: one and many
+//
+
+test('delete one', async function ({ t }) {
+  var a = await db('user').create({ name: 'X' })
+  await db('user').create({ name: 'Y' })
+
+  var n = await db('user').delete({ _id: a.id })
+  t.equal(n, 1)
+
+  var doc = await db('user').get({ _id: a.id })
+  t.equal(doc, null)
+})
+
+test('delete many', async function ({ t }) {
+  await db('user').bulk([{ role: 'x' }, { role: 'x' }, { role: 'y' }])
+  var n = await db('user').delete({ role: 'x' })
+  t.equal(n, 2)
+
+  var docs = await db('user').find({ role: 'x' })
+  t.equal(docs.length, 0)
+})
+
+//
+// COUNT
+//
+
+test('count', async function ({ t }) {
+  await db('user').bulk([{ type: 'a' }, { type: 'a' }, { type: 'b' }])
+  var n = await db('user').count({ type: 'a' })
+  t.equal(n, 2)
+})
+
+//
+// BATCH: base + query + size + sort + limit + fields
+//
+
+test('batch', async function ({ t }) {
+  await db('user').bulk([{ v: 1 }, { v: 2 }, { v: 3 }, { v: 4 }])
+
+  var collected = []
+
+  await db('user').batch({}, { size: 2 }, async function (docs) {
+    for (var i = 0; i < docs.length; i++) collected.push(docs[i].v)
+  })
+
+  t.equal(collected.length, 4)
+  t.ok(collected.includes(1))
+  t.ok(collected.includes(4))
+})
+
+test('batch with query', async function ({ t }) {
+  await db('user').bulk([
+    { type: 'a', v: 1 },
+    { type: 'a', v: 2 },
+    { type: 'b', v: 3 }
+  ])
+
+  var out = []
+
+  await db('user').batch({ type: 'a' }, { size: 10 }, async function (docs) {
+    for (var i = 0; i < docs.length; i++) out.push(docs[i].v)
+  })
+
+  t.equal(out.length, 2)
+  t.ok(out.includes(1))
+  t.ok(out.includes(2))
+})
+
+test('batch with size', async function ({ t }) {
+  await db('user').bulk([{ n: 1 }, { n: 2 }, { n: 3 }, { n: 4 }])
+
+  var chunks = []
+
+  await db('user').batch({}, { size: 2 }, async function (docs) {
+    chunks.push(docs.length)
+  })
+
+  t.equal(chunks.length, 2)
+  t.equal(chunks[0], 2)
+  t.equal(chunks[1], 2)
+})
+
+test('batch respects sort', async function ({ t }) {
+  await db('user').index([['n']])
+
+  await db('user').bulk([{ n: 3 }, { n: 1 }, { n: 2 }])
+
+  var list = []
+
+  await db('user').batch(
+    {},
+    { size: 1, sort: [{ n: 'asc' }] },
+    async function (docs) {
+      list.push(docs[0].n)
+    }
+  )
+
+  t.deepEqual(list, [1, 2, 3])
+})
+
+test('batch respects limit', async function ({ t }) {
+  await db('user').bulk([{ n: 1 }, { n: 2 }, { n: 3 }])
+
+  var list = []
+
+  await db('user').batch({}, { limit: 2 }, async function (docs) {
+    for (var i = 0; i < docs.length; i++) list.push(docs[i].n)
+  })
+
+  t.equal(list.length, 2)
+})
+
+test('batch respects fields', async function ({ t }) {
+  await db('user').bulk([{ name: 'A', age: 10 }])
+
+  var fields = []
+
+  await db('user').batch(
+    { name: 'A' },
+    { fields: ['name'] },
+    async function (docs) {
+      fields.push(Object.keys(docs[0]))
+    }
+  )
+
+  t.deepEqual(fields[0], ['name'])
+})
+
+//
+// DATABASE-LEVEL OPS
+//
+
+test('drop database', async function ({ t }) {
+  await db('user').create({ name: 'A' })
+  await db('user').drop()
+  var doc = await db('user').get({ name: 'A' })
+  t.equal(doc, null)
+})
+
+test('compact', async function ({ t }) {
+  await db('user').create({ name: 'A' })
+  await db('user').update({ name: 'A' }, { name: 'B' })
+  await db.compact('user')
+  t.ok(true)
+})