@eldoy/webdb 0.1.0 → 0.1.2

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
 
@@ -83,6 +83,125 @@ 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
+```
+
+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/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@eldoy/webdb",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Document database client powered by CouchDB.",
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "database",
     "couchdb",

package/spec/tests/spekk.js

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

package/spec/tests/webdb.test.js

@@ -1,242 +0,0 @@
-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)
-})