@eldoy/webdb 0.4.1 → 0.5.0

package/README.md

@@ -1,279 +1,261 @@
 # WebDB
 
-Document database API backed by CouchDB, exposed through a Mongo-style client.
+A small, fast document database API with a portable query language and native backend execution.
+
+WebDB exposes a **single, well-defined interface** (`get` / `set`) designed to cover most web application use cases without sacrificing performance or backend features.
+
+---
+
+## Installation
 
-### Installation
 ```sh
 npm i @eldoy/webdb
 ```
 
-### Usage
+---
+
+## Usage
 
 ```js
 var webdb = require('@eldoy/webdb')
 var db = webdb('http://admin:mysecretpassword@localhost:5984')
+```
+
+WebDB supports **named collections**:
+
+```js
+var users = db('user')
+```
+
+Databases are created automatically on first use.
+
+---
+
+## Insert
+
+### Insert one document
+
+```js
+var doc = await users.set({ name: 'Alice' })
+console.log(doc.id)
+```
+
+The input object may be mutated to attach `id`.
+
+---
 
-// Create one
-var doc = await db('user').create({ name: 'Heimdal' })
+### Bulk insert
 
-// Bulk insert
-var n = await db('user').bulk([
+```js
+var docs = await users.set([
   { name: 'A' },
   { name: 'B' }
 ])
+```
 
-// Update one or many
-var n = await db('user').update(
-  { name: 'A' },
-  { active: true }
-)
-
-// Set (update exactly one)
-var updated = await db('user').set(
-  { name: 'A' },
-  { name: 'B', active: true }
-)
+Returns the inserted documents (same object references).
 
-// Remove (delete exactly one)
-var removed = await db('user').remove(
-  { name: 'B' }
-)
+---
 
-// Put (create or update one)
-var doc = await db('user').put(
-  { email: 'a@example.com' },
-  { email: 'a@example.com', name: 'Alice' }
-)
+## Query (Read)
 
-// Get one (first match)
-var doc = await db('user').get({ name: 'Heimdal' })
+### Get first matching document
 
-// Create indexes
-await db('user').index([
-  ['name'],
-  ['name', 'email']
-])
+```js
+var doc = await users.get({ name: 'Alice' })
+```
 
-// Find
-var docs = await db('user').find({ name: 'Heimdal' })
+Returns `null` if no match exists.
 
-// 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 }
-)
+### Count
 
-// Find with projection
-var docs = await db('user').find(
-  { name: 'Heimdal' },
-  { fields: ['name', 'email'] }
-)
+```js
+var r = await users.get({ active: true }, { count: true })
+console.log(r.count)
+```
 
-// Delete one or many
-var n = await db('user').delete({ active: false })
+---
 
-// Count
-var n = await db('user').count({ name: 'Heimdal' })
+### Streaming / batch reads
 
-// Batch processing (streamed pagination)
-await db('user').batch(
+```js
+await users.get(
   { active: true },
-  { size: 500, sort: [{ created: 'asc' }] },
+  { batch: 100, sort: { created: 1 } },
   async function (docs) {
-    // handle a chunk
+    // process a batch
   }
 )
-
-// Drop a specific database
-await db('user').drop()
-
-// Server-level compact
-await db.compact('user')
-
-// Drop all databases
-await db.drop()
 ```
 
-### Mango Query Options
+Streaming controls **delivery**, not execution.
+Internal buffering is allowed.
+
+---
 
-WebDB queries map directly to CouchDB Mango selectors. All Mango operators and options work as expected through `find()` and `batch()`.
+## Query Operators
 
-#### Comparison Operators
-Mango supports standard comparison operators inside selectors:
+Supported predicates:
 
 ```
-$eq     equal
-$ne     not equal
-$gt     greater than
-$gte    greater than or equal
-$lt     less than
-$lte    less than or equal
-$regex  regular expression matching
+$eq   $ne
+$gt   $gte
+$lt   $lte
+$in   $nin
+$regex
+$exists
 ```
 
-Example:
+Examples:
 
 ```js
-await db('user').find({
-  age: { $gte: 18 }
-})
+await users.get({ age: { $gte: 18 } })
+await users.get({ email: { $regex: '@example.com$' } })
 ```
 
-#### Logical Operators
+Logical operators:
 
-Combine conditions using logical operators:
-
-```
-$and
-$or
-$not
-$nor
+```js
+$and   $or   $not
 ```
 
 Example:
 
 ```js
-await db('user').find({
+await users.get({
   $or: [{ role: 'admin' }, { active: true }]
 })
 ```
 
-#### Sorting
+---
 
-Sorting requires an index on every field in the sort specification:
+## Sorting, Limiting, Projection
 
-```js
-await db('user').index([['created']])
+### Sort
 
-await db('user').find(
+```js
+await users.get(
   {},
-  { sort: [{ created: 'asc' }] }
+  { sort: { created: 1 } }
 )
 ```
 
-#### Limiting
+Sorting may require backend support or indexes.
+If unsupported, the adapter may throw.
 
-Limit returned documents:
+---
+
+### Limit / skip
 
 ```js
-await db('user').find({}, { limit: 10 })
+await users.get({}, { skip: 10, limit: 5 })
 ```
 
-#### Projection (fields)
+---
 
-Return only selected fields:
+### Projection (fields)
 
 ```js
-await db('user').find(
+await users.get(
   {},
-  { fields: ['name', 'email'] }
+  { fields: { name: true, email: true } }
 )
 ```
 
-#### Date Handling
+Notes:
 
-CouchDB stores dates as strings.
-Using ISO-8601 timestamps (`new Date().toISOString()`) enables:
+* Projection is inclusive if any field is `true`
+* `id` is included by default
+* Excluding `id` is **best-effort**
+* Adapters may still return `id`
 
-* correct lexical comparison
-* correct sorting
-* correct `$gt` / `$lt` range queries
+---
 
-Example:
+## Update
+
+### Update matching documents
 
 ```js
-await db('log').find({
-  created: { $gt: "2024-01-01T00:00:00.000Z" }
-})
+var r = await users.set(
+  { active: false },
+  { active: true }
+)
+
+console.log(r.n)
 ```
 
-ISO strings compare and sort in true chronological order.
+Rules:
 
-#### Batch Queries
+* Shallow merge
+* `undefined` removes a field
+* `null` sets field to `null`
 
-`batch()` supports all Mango options:
+---
 
-* `size` (page size)
-* `limit`
-* `sort`
-* `fields`
-* standard selectors
+## Delete
 
-Example:
+### Delete matching documents
 
 ```js
-await db('user').batch(
-  { created: { $gt: cutoff } },
-  { size: 100, sort: [{ created: 'asc' }] },
-  async function (docs) {
-    // process chunk
-  }
-)
+var r = await users.set({ inactive: true }, null)
+console.log(r.n)
 ```
 
-All Mango selectors and options work identically in both `find()` and `batch()`.
-
-
-### 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:
+### Clear collection
 
 ```js
-await db('user').index([['age']])
-await db('user').find({}, { sort: [{ age: 'asc' }] })   // valid
+await users.set({}, null)
 ```
 
-Sorting without the correct index returns an error.
+Deletes all documents in the collection.
 
-**3. Compound indexes**
+---
 
-An index like:
+## Adapter Extensions (Optional)
+
+Adapters may expose additional APIs outside dbspec:
 
 ```js
-await db('user').index([['name', 'email']])
+await users.drop()      // drop a collection
+await db.drop()         // drop all collections
+await db.compact('user')
+await db.info()
 ```
 
-supports selectors and sorts that use `name`, or `name` and `email` together, in the defined order.
+These are **adapter-specific** and non-portable.
 
-**4. Projection (`fields`)**
+---
 
-Projection returns only selected fields.
-Unindexed projection works fine; indexing does not affect `fields`.
+## Escape Hatch (`data`)
 
-**5. Pagination (batch)**
+Native backend access is available via:
 
-`batch()` uses Mango bookmarks internally.
-It respects all options: `sort`, `limit`, `fields`, and `size`.
+```js
+users.data
+```
 
-**6. Create-on-first-use**
+This exposes the underlying client directly.
 
-Databases are auto-created when used. Explicit `drop()` allows clean-state tests.
+Use of `data` is **explicitly non-portable** and bypasses dbspec guarantees.
 
-**7. Null results**
+---
 
-`get()` returns `null` when no match exists.
+## Design Notes
 
-### ID note
+* The reference implementation prioritizes **native execution**
+* No client-side emulation of query semantics
+* Performance scales with the backend
+* Most web apps do not require the escape hatch
+* When switching adapters, application query logic remains stable
 
-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
+## License
 
-Created by [Tekki AS](https://tekki.no)
+ISC
 
-ISC Licensed.
+Created by [Vidar Eldøy](https://eldoy.com)

package/index.js

@@ -3,14 +3,10 @@ var nano = require('nano')
 module.exports = function (url) {
   var server = nano(url)
 
-  var db = function (name) {
-    return api(name, server)
+  function db(name) {
+    return collection(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++) {
@@ -23,269 +19,197 @@ module.exports = function (url) {
   }
 
   db.info = async function () {
-    return await server.info()
+    return server.info()
   }
 
   return db
 }
 
-//
-// COLLECTION-LEVEL API (ordered to match test suite)
-//
+function collection(name, server) {
+  var handle = null
+  var initPromise = null
 
-function api(name, server) {
-  return {
-    //
-    // CRUD
-    //
+  function init() {
+    if (initPromise) return initPromise
 
-    create: async function (doc) {
-      var db = await ensure(name, server)
-      return db.insert(doc)
-    },
+    initPromise = (async function () {
+      try {
+        await server.db.get(name)
+      } catch (e) {
+        try {
+          await server.db.create(name)
+        } catch (e2) {}
+      }
+      handle = server.db.use(name)
+      return handle
+    })()
 
-    bulk: async function (docs) {
-      var db = await ensure(name, server)
-      await db.bulk({ docs: docs })
-      return docs.length
-    },
+    return initPromise
+  }
 
-    put: async function (query, update) {
-      var dbi = await ensure(name, server)
-
-      // find one match
-      var r = await dbi.find({
-        selector: query,
-        limit: 1
-      })
-
-      // create if not found
-      if (!r.docs.length) {
-        var created = await dbi.insert(update)
-        return {
-          _id: created.id,
-          _rev: created.rev,
-          ...update
+  var data = new Proxy(
+    {},
+    {
+      get: function (_, prop) {
+        return async function () {
+          var db = await init()
+          return db[prop].apply(db, arguments)
         }
       }
+    }
+  )
 
-      // update existing
-      var cur = r.docs[0]
-      var next = {}
-
-      for (var k in cur) next[k] = cur[k]
-      for (var k in update) next[k] = update[k]
-
-      var res = await dbi.insert(next)
-
-      next._id = res.id
-      next._rev = res.rev
-      return next
-    },
+  return {
+    data: data,
 
-    update: async function (query, update) {
-      var db = await ensure(name, server)
-      var r = await db.find({ selector: query })
-      if (!r.docs.length) return 0
+    get: async function (query, opts, onBatch) {
+      var db = await init()
+      opts = opts || {}
 
-      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)
+      if (opts.count) {
+        var r = await db.find({ selector: query })
+        return { count: r.docs.length }
       }
 
-      await db.bulk({ docs: out })
-      return out.length
-    },
+      if (onBatch) {
+        var batch = opts.batch || 100
+        var remaining = opts.limit
+        var bookmark = null
 
-    get: async function (query) {
-      var dbi = await ensure(name, server)
-      var r = await dbi.find({ selector: query, limit: 1 })
-      return r.docs[0] || null
-    },
-
-    set: async function (query, update) {
-      var dbi = await ensure(name, server)
-
-      // find one
-      var r = await dbi.find({
-        selector: query,
-        limit: 1
-      })
-
-      if (!r.docs.length) return null
+        for (;;) {
+          var limit = batch
+          if (remaining !== undefined && remaining < limit) {
+            limit = remaining
+          }
 
-      var cur = r.docs[0]
-      var next = {}
-
-      // merge current doc + update
-      for (var k in cur) next[k] = cur[k]
-      for (var k in update) next[k] = update[k]
-
-      // write updated doc
-      var res = await dbi.insert(next)
-
-      // return updated document shape
-      next._id = res.id
-      next._rev = res.rev
-      return next
-    },
+          var q = { selector: query, limit: limit }
+          if (opts.sort) q.sort = normalizeSort(opts.sort)
 
-    remove: async function (query) {
-      var dbi = await ensure(name, server)
+          var mf = opts.fields && normalizeFields(opts.fields)
+          if (mf) q.fields = mf
+          if (bookmark) q.bookmark = bookmark
 
-      // find one
-      var r = await dbi.find({
-        selector: query,
-        limit: 1
-      })
+          var r = await db.find(q)
+          if (!r.docs.length) break
 
-      if (!r.docs.length) return null
+          normalizeDocs(r.docs)
+          await onBatch(r.docs)
 
-      var doc = r.docs[0]
+          if (remaining !== undefined) {
+            remaining -= r.docs.length
+            if (remaining <= 0) break
+          }
 
-      // mark as deleted
-      var res = await dbi.insert({
-        _id: doc._id,
-        _rev: doc._rev,
-        _deleted: true
-      })
-
-      return {
-        _id: res.id,
-        _rev: res.rev
+          if (!r.bookmark || r.docs.length < limit) break
+          bookmark = r.bookmark
+        }
+        return
       }
-    },
-
-    delete: async function (query) {
-      var dbi = await ensure(name, server)
 
-      var r = await dbi.find({ selector: query })
-      if (!r.docs.length) return 0
+      var q = { selector: query }
+      if (opts.sort) q.sort = normalizeSort(opts.sort)
+      if (opts.limit !== undefined) q.limit = opts.limit
+      if (opts.skip) q.skip = opts.skip
 
-      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
-        })
-      }
+      var mf = opts.fields && normalizeFields(opts.fields)
+      if (mf) q.fields = mf
 
-      await dbi.bulk({ docs: out })
-      return out.length
+      var r = await db.find(q)
+      normalizeDocs(r.docs)
+      return r.docs[0] || null
     },
 
-    //
-    // FIND
-    //
+    set: async function (arg, values) {
+      var db = await init()
 
-    find: async function (query, opts) {
-      var dbi = await ensure(name, server)
+      if (Array.isArray(arg)) {
+        var out = []
+        for (var i = 0; i < arg.length; i++) {
+          var d = arg[i]
+          var r = await db.insert(d)
+          d.id = r.id
+          out.push(d)
+        }
+        return out
+      }
 
-      var q = { selector: query }
-      if (opts) {
-        if (opts.sort) q.sort = opts.sort
-        if (opts.limit) q.limit = opts.limit
-        if (opts.fields) q.fields = opts.fields
+      if (values === undefined) {
+        var r = await db.insert(arg)
+        arg.id = r.id
+        return arg
       }
 
-      var r = await dbi.find(q)
-      return r.docs
-    },
+      var r = await db.find({ selector: arg })
+      if (!r.docs.length) return { n: 0 }
+
+      if (values === null) {
+        var del = []
+        for (var i = 0; i < r.docs.length; i++) {
+          del.push({
+            _id: r.docs[i]._id,
+            _rev: r.docs[i]._rev,
+            _deleted: true
+          })
+        }
+        await db.bulk({ docs: del })
+        return { n: del.length }
+      }
 
-    //
-    // INDEX
-    //
+      var upd = []
+      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]
 
-    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] } })
+        for (var k in values) {
+          if (values[k] === undefined) delete next[k]
+          else next[k] = values[k]
+        }
+        upd.push(next)
       }
-    },
 
-    //
-    // COUNT
-    //
-
-    count: async function (query) {
-      var dbi = await ensure(name, server)
-      var r = await dbi.find({ selector: query })
-      return r.docs.length
+      await db.bulk({ docs: upd })
+      return { n: upd.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)
+      handle = null
+      initPromise = null
+    }
+  }
+}
 
-        if (remaining) {
-          remaining -= docs.length
-          if (remaining <= 0) break
-        }
+function normalizeSort(sort) {
+  var out = []
+  for (var k in sort) {
+    if (sort[k] === 1) out.push({ [k]: 'asc' })
+    else if (sort[k] === -1) out.push({ [k]: 'desc' })
+  }
+  return out
+}
 
-        if (!r.bookmark || docs.length < effectiveSize) break
-        bookmark = r.bookmark
-      }
+function normalizeFields(fields) {
+  var include = []
+  for (var k in fields) {
+    if (fields[k]) {
+      include.push(k === 'id' ? '_id' : k)
     }
   }
+  if (include.length) {
+    if (fields.id !== false && include.indexOf('_id') === -1)
+      include.push('_id')
+    return include
+  }
+  return null
 }
 
-//
-// ENSURE DB EXISTS
-//
-
-async function ensure(name, server) {
-  try {
-    await server.db.get(name)
-  } catch (e) {
-    await server.db.create(name)
+function normalizeDocs(docs) {
+  for (var i = 0; i < docs.length; i++) {
+    docs[i].id = docs[i]._id
+    delete docs[i]._id
+    delete docs[i]._rev
   }
-  return server.db.use(name)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eldoy/webdb",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Document database client powered by CouchDB.",
   "publishConfig": {
     "access": "public"