@eldoy/webdb 0.1.1 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ Document database API backed by CouchDB, exposed through a Mongo-style client.
 ### Installation
 ```sh
 npm i @eldoy/webdb
-````
+```
 
 ### Usage
 
@@ -28,6 +28,23 @@ var n = await db('user').update(
   { active: true }
 )
 
+// Set (update exactly one)
+var updated = await db('user').set(
+  { name: 'A' },
+  { name: 'B', active: true }
+)
+
+// Remove (delete exactly one)
+var removed = await db('user').remove(
+  { name: 'B' }
+)
+
+// Upsert (create or update one)
+var doc = await db('user').upsert(
+  { email: 'a@example.com' },
+  { email: 'a@example.com', name: 'Alice' }
+)
+
 // Get one (first match)
 var doc = await db('user').get({ name: 'Heimdal' })
 
@@ -83,6 +100,126 @@ await db.compact('user')
 await db.drop()
 ```
 
+### Mango Query Options
+
+WebDB queries map directly to CouchDB Mango selectors. All Mango operators and options work as expected through `find()` and `batch()`.
+
+#### Comparison Operators
+Mango supports standard comparison operators inside selectors:
+
+```
+$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
+```
+
+Example:
+
+```js
+await db('user').find({
+  age: { $gte: 18 }
+})
+```
+
+#### Logical Operators
+
+Combine conditions using logical operators:
+
+```
+$and
+$or
+$not
+$nor
+```
+
+Example:
+
+```js
+await db('user').find({
+  $or: [{ role: 'admin' }, { active: true }]
+})
+```
+
+#### Sorting
+
+Sorting requires an index on every field in the sort specification:
+
+```js
+await db('user').index([['created']])
+
+await db('user').find(
+  {},
+  { sort: [{ created: 'asc' }] }
+)
+```
+
+#### Limiting
+
+Limit returned documents:
+
+```js
+await db('user').find({}, { limit: 10 })
+```
+
+#### Projection (fields)
+
+Return only selected fields:
+
+```js
+await db('user').find(
+  {},
+  { fields: ['name', 'email'] }
+)
+```
+
+#### Date Handling
+
+CouchDB stores dates as strings.
+Using ISO-8601 timestamps (`new Date().toISOString()`) enables:
+
+* correct lexical comparison
+* correct sorting
+* correct `$gt` / `$lt` range queries
+
+Example:
+
+```js
+await db('log').find({
+  created: { $gt: "2024-01-01T00:00:00.000Z" }
+})
+```
+
+ISO strings compare and sort in true chronological order.
+
+#### Batch Queries
+
+`batch()` supports all Mango options:
+
+* `size` (page size)
+* `limit`
+* `sort`
+* `fields`
+* standard selectors
+
+Example:
+
+```js
+await db('user').batch(
+  { created: { $gt: cutoff } },
+  { size: 100, sort: [{ created: 'asc' }] },
+  async function (docs) {
+    // process chunk
+  }
+)
+```
+
+All Mango selectors and options work identically in both `find()` and `batch()`.
+
+
 ### Notes on Indexing, Sorting, and Mango Queries
 
 **1. Selector fields and indexes**

package/index.js

@@ -46,6 +46,39 @@ function api(name, server) {
       return docs.length
     },
 
+    upsert: 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
+        }
+      }
+
+      // 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
+    },
+
     update: async function (query, update) {
       var db = await ensure(name, server)
       var r = await db.find({ selector: query })
@@ -70,39 +103,59 @@ function api(name, server) {
       return r.docs[0] || null
     },
 
-    //
-    // FIND
-    //
-
-    find: async function (selector, opts) {
+    set: async function (query, update) {
       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
-      }
+      // find one
+      var r = await dbi.find({
+        selector: query,
+        limit: 1
+      })
 
-      var r = await dbi.find(q)
-      return r.docs
-    },
+      if (!r.docs.length) return null
 
-    //
-    // INDEX
-    //
+      var cur = r.docs[0]
+      var next = {}
 
-    index: async function (list) {
+      // 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
+    },
+
+    remove: async function (query) {
       var dbi = await ensure(name, server)
-      for (var i = 0; i < list.length; i++) {
-        await dbi.createIndex({ index: { fields: list[i] } })
+
+      // find one
+      var r = await dbi.find({
+        selector: query,
+        limit: 1
+      })
+
+      if (!r.docs.length) return null
+
+      var doc = r.docs[0]
+
+      // mark as deleted
+      var res = await dbi.insert({
+        _id: doc._id,
+        _rev: doc._rev,
+        _deleted: true
+      })
+
+      return {
+        _id: res.id,
+        _rev: res.rev
       }
     },
 
-    //
-    // DELETE
-    //
-
     delete: async function (query) {
       var dbi = await ensure(name, server)
 
@@ -123,6 +176,35 @@ function api(name, server) {
       return out.length
     },
 
+    //
+    // FIND
+    //
+
+    find: async function (query, opts) {
+      var dbi = await ensure(name, server)
+
+      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
+      }
+
+      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] } })
+      }
+    },
+
     //
     // COUNT
     //

package/package.json

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