Not a Propaganda Machine

    xcouch

    0.1.0 • Public • Published

    xCouch

    Installation

    npm install xcouch

    Usage Examples

    Create a new user and the dabase for the user

    var Store = require('xcouch')
     
    Store.connect('http://admin:pass@localhost:5984', function(err) {
      if(err) throw err
      Store.createUser('name', 'pass', function(err, id, rev) {
        if(err) throw err
        // Hooray, we created a new user
    })

    How To Create Own Store Object Models

    Create a file mymodel.js:

    var util = require('util')
      , Store = require('xcouch')
      ;
     
    // Add the model to the model-registry of the store
    Store.addModel('MyModel', MyModel)
     
    // Create a new model
    function MyModel(id, rev) {
      if(!(this instanceof MyModel)) return new MyModel(id, rev)
      Store.call(this, id, rev)
    }
    util.inherits(MyModel, Store) // The model must inherit from Store

    To use MyModel do the following:

    var Store = require('xcouch')
     
    // Load the model
    require('./mymodel')
     
    // Connects to the store (CouchDB)
    Store.connect('http://admin:pass@localhost:9548', function(err) {
      if(err) throw err
      
      // Connects as a user of the store
      Store.connectUser('name', 'pass', function(err, user, getObject, db, nano) {
        if(err) throw err
        
        // Creates a new object
        var myObject = getObject('MyModel')
        
        // Saves the new object
        myObject.save(function(err, written) {
          if(err) throw err
          
          if(written) {
            // changes saved
          } else {
            // nothing changed, so nothing written :-)
          }
        })
        
        // Loads an existing object (document)
        var myObject2 = getObject('MyModel', 'idOfTheDocument')
        myObject2.load(function(err) {
          if(err) {
            // Not found
            // We could save it here under the id 'idOfTheDocument'
            // But we'll throw:
            throw err
          }
          // Print the data
          console.log(myObject2.get())
        })
      })
    })

    Security

    Rules

    • One database per user.
    • By default, the user owns its database exclusively. No other
      user can read from or write to it.
    • Admins can do everything.
    • xCouch will never create accounts with administrative privileges.
    • Only admins can create users. Direct sign-up to the CouchDB
      will be disabled per '_security' document.

    API

    Setup

    Store.connect(dsn, callback)
    callback(err)

    Users

    Store.createUser(name, pass, callback)
    callback(err, id, rev)

    Store.connectUser(name, pass, callback)
    callback(err, doc, getObject, db, nano)

    Store.destroyUser(name, pass, callback)
    callback(err, doc)

    Store Object Models

    Store.addModel(name, constructor)

    Class: Store

    Properties

    .dirty

    .data

    .db

    Methods

    Configuration Accessors

    .type([type])

    .id([id])

    .rev([rev])

    Field Accessors

    .get([field])

    .set([hash] || [field, value])

    Persistence

    .exists(callback)
    callback(err, exists)

    .load(callback)
    callback(err)

    .save([force, ] callback)
    callback(err, written)

    .remove(callback)
    callback(err, written)

    Related Object Accessors

    .getOne(type, cb)

    .getMany(type, cb)

    .addOne(obj)

    .addMany(obj || array of objects)

    Changes

    .subscribe() .unsubscribe()

    How To Run The Tests

    WARNING: The tests and xCouch will make changes to your CouchDB
    and those changes will not be reverted automatically. Please make
    backups if you have to undo the changes xCouch made to your
    CouchDB.

    Understood? Ready? Then:

    Copy test/options.json-dist to test/options.json and edit
    the copy:

    {
      "dsn": "http://[admin]:[pass]@localhost:5984",
      "user": {
        "name": "xcouchtestuser",
        "pass": "acb123"
      },
      "user_one": {
        "name": "xcouchtestuserone",
        "pass": "acb123"
      },
      "user_two": {
        "name": "xcouchtestusertwo",
        "pass": "acb123"
      }
    }

    Now type mocha -R spec --ignore-leaks and hit enter.

    And again, running the tests will change your CouchDB in a way
    you might not like. Don't blame the author for lost data or ask
    the author to clean up your database afterwards.

    Here is the output of the tests taken from a Win7Starter Netbook
    :P

    D:\Workspace\couchapps\q3\_xcouch>mocha -R spec --ignore-leaks --bail
    
    
      xCouch: Store
        V needs to connect (119ms)
        The Store User
          V must have a valid username (^[a-z][a-z0-9\_\$()\+\-\/]*$)
          V must be created (965ms)
          V and needs to connect too
          The connect of the user gave us
            V the user-document
            V a function getObject() to get objects from the db of the user
            V the db of the user as an nano-db-object
            V a nano-object to interact with the couch as the user
          A Store Object
            V will be created with getObject()
            V inherits from Store
            V is some .type()
            V has .get() to get and .set() to set fields of data
            V is .dirty after a change
            can be saved with .save()
              V will be written if dirty
              V will not be written if not dirty
              V can be forced to be written even if not dirty
            After a save, the data
              V has a data property that equals the return value of .get()
              V has a _id field that equals the return value of .id()
              V has a _rev field that equals the return value of .rev()
              V has a type field that equals the return value of .type()
            can be loaded from the store with .load()
              V will hold the same data
            can be removed from the store with .remove()
              V .
              V will be gone in database
          A new Store Object
            V will always be written on .save()
          Related Objects
            One to One
              .addOne()
                V adds an object
              .save() will save all related objects and the object to the db
                V
              .getOne()
                V gets the object previously added and saved (39ms)
              .remove() will remove all related objects and the object from the db
                V  (43ms)
            One to Many
              .addMany()
                V adds many objects
              .save() will save all related objects and the object to the db
                V  (107ms)
              .getMany()
                V gets the objects previously added and saved (58ms)
              .remove() will remove all related objects and the object from the db
                V  (138ms)
          Changes
            - .subscribe()
            - .unsubscribe()
    
      xCouch: Security
        V we need to connect (39ms)
        V someone creates UserOne (96ms)
        V someone creates UserTwo (80ms)
        V UserOne connects
        V UserOne tries put a doc into the db of UserTwo: Not allowed.
        V UserOne tries to read a doc from the db of UserTwo: Not allowed.
        V UserOne tries to remove a doc from the db of UserTwo: Not allowed.
        V UserOne tries to list db "_users": Not allowed.
        V UserOne tries to list the db of UserTwo: Not allowed.
    
    
      ? 43 tests complete (2854ms)
       2 tests pending
    
    

    MIT License

    Copyright (c) 2012 Oliver Leics oliver.leics@gmail.com

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Keywords

    none

    Install

    npm i xcouch

    DownloadsWeekly Downloads

    7

    Version

    0.1.0

    License

    none

    Last publish

    Collaborators

    • pureppl