Have ideas to improve npm?Join in the discussion! »

    picodb

    1.0.1 • Public • Published

    PicoDB

    NPM version GitHub last commit Travis CI Test coverage Dependencies status Dev Dependencies status npm bundle size License

    PicoDB is an in-memory database that stores JSON like documents. It runs both on Node.js and in the ES6 compliant browsers.

    PicoDB manages the documents as MongoDB for a collection. It provides a flexible API (MongoDB like) to insert, update, delete and find documents.

    PicoDB is useful when you want to manage documents directly inside your Web App.

    Nota: From PicoDB 1.x IE browsers are not supported anymore. PicoDB 0.12 is the latest version that is IE compliant.

    Quick Startup

    Documents

    A document is a Javascript literal object. It is similar to a JSON object. A set of key-value pairs.

    When a document is inserted into the database, it gets an unique id that is a string of 16 characters. Thus, a document into the database looks like:

    { _id: 'atpl4rqu8tzkt9', name: { first: 'John', last: 'Doe' }, email: 'john@doe.com' }

    Create the database

    On Node.js:

    const PicoDB = require('picodb');
    const db = PicoDB();

    In the browser:

    const db = PicoDB();

    Listen for a Response

    There is now three ways to listen a response from a PicoDB instance:

    • Via Callback:
    db.find({}).toArray((err, resp) => {
        // your code
    });
    • Via then/catch
    db.find({}).toArray()
        .then((resp) => {
          // your code
        })
        .catch((err) => {
          // your code
        });
    • Via async/await
    async function fn() {
        ...
        const resp = await db.find({}).toArray();
        ...
    }

    Insert documents

    PicoDB provides two methods for inserting documents.

    A method for inserting one document:

    // doc contains the inserted document with its unique id.
    const doc = await db.insertOne({ a: 1 });

    And a method for inserting a set of documents:

    // docs contains the inserted documents with their unique ids.
    const docs = await db.insertMany([{ a: 1 }, { a: 2, b: 2 }]);

    Update documents

    PicoDB provides two methods for updating documents.

    A method for updating the first document that matches the query:

    // doc contains the updated document.
    const doc = await db.updateOne({ a: 1 }, { c: 'aaa' });

    And a method for updating all the documents that match the query:

    // docs contains the updated documents.
    const docs = await db.updateMany({ a: 1 }, { c: 'aaa' });

    The first method replaces the first document (the oldest one) into the database that contains the key-value pair { a: 1 } by the new document { c: 'aaa' } while the second method replaces all the documents that contain this key-value pair by the new document.

    These methods replace the document(s) but they do not alter their _id.

    The update methods provide the two operators $set and $unset for a finest update granularity.

    The following operation:

    const docs = await db.updateOne({ a: 1 }, { $set: { c: 'new' }});

    selects the first document into the database that contains the field a = 1 (or the key-value pair a = 1) and replaces the value of the field c by new or adds the field if it doesn't exist.

    while the following operation:

    const docs = await db.updateOne({ a: 1 }, { $unset: { c: 'aaa' }});

    removes the field c = 'aaa'.

    Delete documents

    PicoDB provides two methods for deleting documents.

    A method for deleting the first document that matches the query:

    // num contains the number of deleted documents (here 0 or 1).
    const num = await db.deleteOne({ a: 1 });

    And a method for deleting all the documents that match the query:

    // num contains the number of deleted documents.
    const num = await db.deleteMany({ a: 1 });

    Count documents

    PicoDB provides one method to count the number of the documents into the database that match the query.

    // num contains the number of documents that match the query.
    const count = await db.count({ a: 1 });

    Find documents

    PicoDB provides one method to dump the documents that match the query.

    The following instruction:

    const docs = await db.find({}).toArray();

    dumps all the documents into the database as the query {} does not filter anything.

    While the instruction:

    // docs is an array of documents that match the query.
    const docs = await db.find({ a: 1 }).toArray();

    dumps the documents that contain the field a with the value 1.

    Select the fields to extract

    PicoDB allows selecting the fields to extract from the database.

    The following instruction:

    const docs = await db.find({}, { c: 1, d: 1 }).toArray();

    dumps all the documents but extracts only the fields _id, c and d. The field _id is extracted by default. You can reject it by adding _id: 0 to the expression:

    // docs is an array of documents that match the query.
    const docs = await db.find({}, { _id: 0, c: 1, d: 1 }).toArray();

    Instead of defining the fields to extract, you can set the fields to exclude. This instruction:

    // docs is an array of documents that match the query.
    const docs = await db.find({}, { c: 0, d: 0 }).toArray();

    dumps all the documents with all the fields except c and d.

    Query Operators

    PicoDB provides a subset of MongoDB's Query Operators like $eq, $gt, $gte, $lt, etc.

    These operators allow more sophisticated queries.

    The following instruction:

    const docs = await db.find({ a: { $gt: 1 }, b: { $lt : 6 }}).toArray();

    dumps all the documents with the field a having a value greater than 1 AND the field b having a value lower than 6.

    Listen

    PicoDB provides, through a plugin, the following custom events change, insert, update and delete that are fired when a document into the database is modified.

    The following instruction:

    const docs = await db.on('change');

    is executed when documents are inserted, updated or deleted.

    This option uses the NPM package @mobilabs/messenger. You need to install it before instantiating PicoDB like that:

    import Messenger from 'path/to/@mobilabs/messenger';
    
    PicoDB.plugin({ messenger: Messenger });
    const db = PicoDB();

    API

    Constructor

    Constructor   | Description
    
    PicoDB        | Creates the PicoDB object (without the operator new).
    

    Static Methods

    Static methods | Description
    
    plugin         | Adds and external library.
    

    Methods

    PicoDB implements the following methods:

    Method     | Description
    
    count      | Counts number of matching documents into the db.
    deleteMany | Deletes multiple matching documents into the db.
    deleteOne  | Deletes the first matching document into the db.
    insertMany | Inserts an array of documents into the db.
    insertOne  | Inserts one document into the db.
    updateMany | Updates multiple matching documents into the db.
    updateOne  | Updates the first matching documents into the db.
    find       | Finds multiple matching documents into the db.
    toArray    | Returns the array of documents selected with the find method.
    on         | Adds an event listener (alias of addEventListener).
    one        | Adds an event listener that fires once (alias of addOneTimeEventListener).
    off        | Removes the event listener (alias of removeEventListener).
    

    Query Operators

    Comparison Operators

    PicoDB implements the following Comparison Operators:

    Operator | Description
    
    $eq      | Matches values that are equal to a specified value.
    $gt      | Matches values that are greater than a specified value.
    $gte     | Matches values that are greater than or equal to a specified value.
    $lt      | Matches values that are less than a specified value.
    $lte     | Matches values that are less than or equal to a specified value.
    $ne      | Matches all values that are not equal to a specified value.
    $in      | Matches any of the values specified in an array.
    $nin     | Matches none of the values specified in an array.
    

    Element Operators

    Operator | Description
    
    $exists  | Matches documents that have the specified field.
    

    Logical Operators

    Operator | Description
    
    $and     | Joins query clauses with a logical AND returns all documents that match the conditions of either clause.
    $or      | Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
    $not     | Inverts the effect of a query expression and returns documents that do not match the query expression.
    

    Geospatial Operators

    Operator       | Description
    
    $geoWithin     | Selects geometries within a bounding GeoJSON geometry.
    $geoIntersects | Selects geometries that intersect with a GeoJSON geometry.
    $near          | Selects geometries that are inside limits on the Earth sphere.
    

    $geoWithin and $geoIntersects GeoJSON geometries could only by Polygon and MultiPolygon.

    geoWithin supports Point, LineString, MultiPoint, MultiLineString and Polygon geometries.

    geoIntersects supports LineString and Polygon geometries.

    Geometry Specifiers

    $geoWithin could be used with the legacy shape operators:

    $box           | Specifies a rectangle to return documents that are within the rectangle.
    $polygon       | Specifies a rectangle to return documents that are within the polygon.
    $center        | Specifies a circle to return documents that are within the circle.
    $centerSphere  | Specifies a earth-like sphere to return documents that are within the sphere.
    

    $near could be used with the following operators:

    $minDistance   | Specifies a minimum distance to limit the results of queries.
    $maxDistance   | Specifies a maximum distance to limit the results of queries
    

    $minDistance and $maxDistance specify the distance in meters.

    Update Operators

    Field Operators

    Operator     | Description
    
    $inc         | Increments the value of the field by the specified amount.
    $mul         | Multiplies the value of the field by the specified amount.
    $rename      | Renames a field.
    $set         | Sets the value of a field in a document or adds it.
    $unset       | Removes the specified field from a document.
    $min         | Updates the field if the specified value is less than the existing field value.
    $max         | Updates the field if the specified value is greater than the existing field value.
    $currentDate | Sets the value of a field to current date.
    

    Array Operators

    Operator     | Description
    
    $pop         | Removes the first or last item of an array.
    $pullAll     | Removes all matching values from an array.
    $pull        | Removes all the array elements that match a specified query.
    $push        | Adds an item to an array.
    
    Array Update Operator Modifiers

    $push operator can be used with the following modifiers:

    Operator     | Description
    
    $each        | Modifies the $push and operator to append multiple items for array updates.
    $slice       | Modifies the $push operator to limit the size of updated arrays.
    $position    | Modifies the $push operator to specify the position in the array to add elements.
    
    Array Update Comparison Operators

    pull operator can be used with the following comparison operators:

    Operator     | Description
    
    $eq          | Matches values that are equal to a specified value.
    $gt          | Matches values that are greater than a specified value.
    $gte         | Matches values that are greater than or equal to a specified value.
    $lt          | Matches values that are less than a specified value.
    $lte         | Matches values that are less than or equal to a specified value.
    $ne          | Matches all values that are not equal to a specified value.
    $in          | Matches any of the values specified in an array.
    $nin         | Matches none of the values specified in an array.
    

    Events (optional)

    Event type   | Description
    
    change       | Fires when a document is modified with the methods insert, update or delete.
    insert       | Fires when a document is inserted into the db.
    update       | Fires when one or multiple documents are updated into the db.
    delete       | Fire when one or multiple documents are deleted from the db.
    

    License

    MIT.

    Install

    npm i picodb

    DownloadsWeekly Downloads

    14

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    346 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar