Document database client powered by CouchDB.
npm install @eldoy/webdbA 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.
---
``sh`
npm i @eldoy/webdb
---
`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.
---
`js`
var doc = await users.set({ name: 'Alice' })
console.log(doc.id)
The input object may be mutated to attach id.
---
`js`
var docs = await users.set([
{ name: 'A' },
{ name: 'B' }
])
Returns the inserted documents (same object references).
---
`js`
var doc = await users.get({ name: 'Alice' })
Returns null if no match exists.
---
`js`
var r = await users.get({ active: true }, { count: true })
console.log(r.count)
---
`js`
await users.get(
{ active: true },
{ batch: 100, sort: { created: 1 } },
async function (docs) {
// process a batch
}
)
Streaming controls delivery, not execution.
Internal buffering is allowed.
---
Supported predicates:
`
$eq $ne
$gt $gte
$lt $lte
$in $nin
$regex
$exists
Examples:
`js`
await users.get({ age: { $gte: 18 } })
await users.get({ email: { $regex: '@example.com$' } })
Logical operators:
`js`
$and $or $not
Example:
`js`
await users.get({
$or: [{ role: 'admin' }, { active: true }]
})
---
`js`
await users.get(
{},
{ sort: { created: 1 } }
)
Sorting may require backend support or indexes.
If unsupported, the adapter may throw.
---
`js`
await users.get({}, { skip: 10, limit: 5 })
---
`js`
await users.get(
{},
{ fields: { name: true, email: true } }
)
Notes:
* Projection is inclusive if any field is true
* is included by defaultid
* Excluding is best-effortid
* Adapters may still return
---
`js
var r = await users.set(
{ active: false },
{ active: true }
)
console.log(r.n)
`
Rules:
* Shallow merge
* undefined removes a fieldnull
* sets field to null
---
`js`
var r = await users.set({ inactive: true }, null)
console.log(r.n)
---
`js`
await users.set({}, null)
Deletes all documents in the collection.
---
Adapters may expose additional APIs outside dbspec:
`js`
await users.drop() // drop a collection
await db.drop() // drop all collections
await db.compact('user')
await db.info()
These are adapter-specific and non-portable.
---
)Native backend access is available via:
`js`
users.data
This exposes the underlying client directly.
Use of data` is explicitly non-portable and bypasses dbspec guarantees.
---
* 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
---
ISC
Created by Vidar Eldøy