A Deno π¦ persistent, embeddable and optimized NoSQL database for JS & TS .
Documentation
Report a Bug
Β·
Request Feature
.
Support Us
DnDB is a javascript persistent database written for Deno and available for Typescript.
Inspired by NeDB, DnDB is a robust but minimalist database engine written on JS that uses/emulates the mongo query API to edit and find data, making it 100% exportable to a mongojs environment.
Notice: This project is under development, so it is subject to future improvements and changes.
DnDB is an incredibly fast and powerful data store. All methods are streamed and buffered to optimize data reading/writing. DnDB is not only faster, but it consumes less resources (RAM) since only a small portion of the data stream is stored in memory by the buffer, enabling optimal performance on large data collections.
Run the demo to test DnDB in a server environment. Also this demo lives on Codesandbox
deno.land
import Datastore from "https://deno.land/x/[email protected]/mod.ts";
nest.land
import Datastore from "https://x.nest.land/[email protected]/mod.ts";
DnDB works by instantiating collections stored in a specific file given by the user in the instance configuration. By default the created instance exposes the necessary methods to work the datastore.
All the api methods are asynchronous by default, so they return promises, but it's also possible to pass a callback to them to work in a traditional mongo way.
import Datastore from "https://deno.land/x/[email protected]/mod.ts";
const db = new Datastore({ filename: "./database.db", autoload: true });
When you instantiate a collection you can pass it a config object with a couple of options:
-
filename
: The filename is the absolute path to your target file. If no filename is provided, DnDB will automatically create one in the current working directory, and if a full path is not specified, it will resolve the file name within the CWD. -
autoload
: The autoload option runs theloadDatabase
method which creates the persistent file the first time DnDB is running in your project, this is optional, but if the loadDatabase method is not executed, the instance will not work until the persistent file exists. -
bufSize
: The bufSize parameter rewrites the default size of the buffer. It must be indicated in numbers and represents the amount of bytes to be allocated. By default 4096 bytes.
Notice: The configuration content is currently in alpha, more options will be available soon.
All data types are allowed, but field names starting with '$' are reserved for data querying.
If the document does not contain an _id field, DnDB will automatically generate one for you (a RFC4122 UUID alphanumerical string). The _id of a document, once set, shouldn't be modified.
let obj = {
name: "denyn",
lastName: "crawford",
};
let insertion = await db.insert(obj);
// OR
db.insert(obj, (insertion) => {
// ...foo(insetion)
});
To insert documents DnDB exposes the method:
-
insert
: -
returns: Array/object with the inserted documents.
The insert method receives two arguments:
data
: Json data to insertcallback
(optional): The callback function to get the data inserted.
You can also insert several documents at the same time by wrapping them in an array.
let foo = "foo";
db.insert([{ name: "denyn" }, { name: foo }], (insertion) => {
// ...foo(insetion)
});
To find documents DnDB exposes the methods:
-
find
: Finds all the documents that match the query.- returns: array of matching documents
-
findOne
: Finds the first document that matches the query.- returns: exact first matching object
You can select documents based on field equality or use comparison operators
($lt
, $lte
, $gt
, $gte
, $in
, $nin
, $neq
). You can also use logical
operators $or
, $and
, $not
and $eq
. See below for the syntax.
You can use regular expressions in two ways: in basic querying in place of a string, or with the $regex operator.
Example of document querying:
Notice: See all rules and operators list here
db.find({ name: "Denyn" }, {}, (docs) => {
console.log(docs);
});
// or
let docs = await db.find({ name: "Denyn" });
// Finding unique document
let docs = await db.findOne({ username: "denyncrawford" });
// Deep querying syntax:
let docs = await db.find({ fullName: { lastName: "Crawford" } });
You can also use dot notation to find documents by deep querying.
let docs = await db.find({ "fullName.lastName": "Crawford" });
// Using dot notation to find inside arrays:
let docs = await db.find({ "list.games.0": "Doom" });
If you want to know how to advance query documents please read this
You can give find
and findOne
an optional second argument, projections. The
syntax is the same as MongoDB: { a: 1, b: 1 }
to return only the a and b
fields, { a: 0, b: 0 }
to omit these two fields. You cannot use both modes at
the time, except for _id which is by default always returned and which you can
choose to omit. You can project on nested documents.
Notice: See all rules and operators list here
db.find({ planet: "Mars" }, { planet: 1, system: 1 }, function (docs) {
// docs is [{ planet: 'Mars', system: 'solar', _id: 'id1' }]
});
To update documents DnDB exposes the method:
-
update
- returns: array with the new updated collection
-
updateOne
- returns: object with the new updated document.
The update method follows the same query rules as in find
and findOne
at
first argument to get the update target document and as a second agument it
receives the aggregation operators that modifies the matching fileds values ββby
following the aggregation rules.
Notice: See all rules and operators list here
db.update({ name: "denyn" }, { $set: { pet: "Boots" } }, (update) => {
// ...foo(update)
});
// OR
let update = await db.update({ name: "denyn" }, { $set: { pet: "Boots" } });
To remove documents DnDB exposes the method:
-
remove
- returns: array with the new removed collection
-
removeOne
- returns: object with the new removed document
The remove method follows the same query rules as in find
and findOne
at
first argument, it will remove all the documents that matches the query.
db.remove({ _id: "id2" }, function (newDoc) {
// ...foo(newDoc)
});
//OR
const { remove } = db;
await remove({ _id: "id2" });
Notice: If you want to unset a value from the document you must use update with the $unset operator. See all rules and operators list here
- Standard methods
- Database from datastores factory
- Read and write streams and buffer
- Global Queue executor
- Event hooks on all the API usage
- Count method
- Improve documentation
- Prevent updating immutable data
- Error handlers.
- SORT, SKIP, and LIMIT modifier methods support.
Since it is a standard, the API will not be subject to drastic changes, but its internal working will.
Copyright (c) Crawford.
Type | Command |
---|---|
Format | deno fmt |
Lint | deno lint --unstable --ignore=test,demo |
Test | deno test --unstable --allow-read=. --allow-write=db.db,db.db.updated |