Narcoleptic Possum Mob

    elisa-pouchdb

    0.3.3 • Public • Published

    NPM version Build Status Dependency Status devDependency Status

    PouchDB Elisa.js driver. This driver complies with Elisa 0.3.1 spec.

    Proudly made with ♥ in Valencia, Spain, EU.

    Features

    • This driver allows to use the schema concept.
    • This driver can work with key-value stores and document collections.
    • This driver can connect to local databases (browser apps and Node.js apps) and remote databases (PouchDB Server or CouchDB).
    • This driver can be used with an in-memory database.
    • This driver can work with design documents and views.

    PouchDB is a document database, where all the documents are saved into a database, without collection support and without schema support. But this driver simulates key-value stores and document collections and schemas.

    Table of contents

    Install

    npm install elisa-pouchdb
    

    Driver load

    const Driver = require("elisa-pouchdb").Driver;
    const driver = Driver.getDriver("PouchDB");
    

    We can use the following names:

    • PouchDB
    • Pouch

    Connections

    Connection to local database

    var cx = driver.createConnection({
      db: "DB name",
      location: "directory path",
      autoCompaction: true|false,
      adapter: "adapter name",
      revsLimit: number
    });
    

    The location option is used in Node.js apps to indicate where to save the database.

    Connection to in-memory database

    var cx = driver.createConnection({});
    

    Connection to remote database

    We can connect to a PouchDB Server or a CouchDB server:

    var cx = driver.createConnection({
      db: "db name",
      protocol: "http|https",
      host: "hostname",
      port: port,
      username: "username",
      password: "password",
      skipSetup: true|false
    });
    

    To indicate a remote connection, we must indicate protocol, host, port or username as minimum.

    When the server has no authentication, we can skip username and password.

    Schemas

    The schemas doesn't support by PouchDB/CouchDB natively. But this driver does it. In many cases, the schemas are associated to design documents.

    To get a schema object, we can use the methods: getSchema() and findSchema() of the Database class. To indicate the design document name, use the design option.

    Next, some illustrative examples:

    var hr = db.getSchema("hr");
    var hr = db.getSchema("hr", {design: "hr"});
    

    Key-value stores

    PouchDB is a document database, but we can use this driver to save documents as values in key-value stores.

    To get a store object, we can use the getStore() and findStore() methods. With the view option, we can indicate the view name if the store is associated to a view.

    Examples:

    var emp = cx.db.getStore("hr.employee");
    var emp = cx.db.getStore("hr.employee", {design: "hr", view: "employees"});
    

    The view option can be:

    • A string, the view name.
    • true, then the driver will use the store name as view name.

    Inserting a key-value

    The insert() method is used to insert documents how indicated in the Elisa spec. We must not forget to indicate the id property, this is the document key.

    Example:

    emp.insert({id: "Elvis Costello", year: 1954}, function(error) {});
    

    If the document exists, this is overwritten.

    We can insert several documents:

    store.insert([
      {id: "one", x: 1, y: 1},
      {id: "two", x: 1, y: 2},
      {id: "three", x: 1, y: 3}
    ], function(error) {
    
    });
    

    Updating a value

    If we need to update all the documents, we must use the insert() method. But if we want to update some fields, the update() method:

    store.update({id: "the key", {x: "new value"}}, function(error) {});
    

    Removing a key-value

    //one key-value
    store.remove({id: "the key"}, function(error) {});
    
    //all
    store.remove({}, function(error) {});
    

    Finding values

    //one document
    store.find({id: "the key"}, function(error, doc) {});
    
    //all documents
    store.findAll(function(error, result) {});
    

    Observations

    Please, see the Elisa.js spec to know how to use the stores. This driver complies with the spec.

    Document collections

    PouchDB is a document database. This DBMS doesn't support the collection concept. But this driver does it.

    To get a collection object, we must use the getCollection() and findCollection() methods. If the collection is associated to a view, we can indicate it with the view option:

    • If its value is true, the view name is the collection name.
    • If its value is a string, the view name is the specified one.

    Examples:

    var emp = cx.db.getCollection("hr.employees");
    var emp = cx.db.getCollection("hr.employees", {design: "hr", view: "employees"});
    

    The options can be:

    • design (string). Indicate the design document name if needed.
    • view (string). Indicate the view name if needed.
    • id (string). Indicate how to generate the id field if not indicated in an insert: uuid, generating a UUID; sequence, using a sequence. Default: uuid.
    • sequence (string). If id=="sequence", the sequence key. Default: __sequence__.

    Inserting documents

    //one document
    coll.insert({x: 1, y: 1}, function(error) {});
    
    //several documents
    coll.insert([{x: 1, y: 1}, {x: 1, y: 2}], function(error) {});
    

    If the document has no id, the driver sets it.

    Updating documents

    coll.update({x: 1}, {y: {$inc: 1}}, function(error) {});
    

    Removing documents

    //several documents
    coll.remove({x: 1}, function(error) {});
    
    //all documents
    coll.remove({}, function(error) {});
    

    Finding documents

    coll.find({x: 1}, function(error, result) {});
    coll.findOne({x: 1}, function(error, doc) {});
    

    We also can use the query interface:

    var q = coll.q();
    q.project("x", "y").filter({x: 1}).sort("x").run(function(error, result) {});
    q.project("x", "y").find({x: 1}, function(error, result) {});
    

    Observations

    Please, see the Elisa.js spec to know how to use the collections. This driver complies with the spec.

    Install

    npm i elisa-pouchdb

    Homepage

    elisajs.org

    DownloadsWeekly Downloads

    28

    Version

    0.3.3

    License

    none

    Last publish

    Collaborators

    • elisajs