Permalink
Browse files

Pure-Json-on-Couch

  • Loading branch information...
0 parents commit bb0f119fec77060b71208f2e4d40727ab43caf11 @landeiro committed Apr 26, 2011
Showing with 943 additions and 0 deletions.
  1. +154 −0 README.md
  2. BIN couchdb.png
  3. +441 −0 lib/PJsonCouch.js
  4. +48 −0 testBasics.js
  5. +56 −0 testDB.js
  6. +56 −0 testDesign.js
  7. +144 −0 testDocs.js
  8. +44 −0 testServer.js
154 README.md
@@ -0,0 +1,154 @@
+# PJsonCouch
+
+(PJs-on-Couch) is a [node.js](http://nodejs.org/) client lib for [CouchDB](http://couchdb.apache.org/).
+
+PJsonCouch it means Pure-Json-on-Couch but it should be read PJs-on-Couch :)
+
+## Why.
+The main idea is to use as most as possible [JSON](http://www.json.org/) for data transport.
+JSON is a more clean manner to structure data and understand the arguments and requests sent to CouchDB.
+
+For example the CouchDB URL invocation:
+
+ /developers/_design/basic_info/_view/by_name?reduce=false&key="Jane"
+
+translates to:
+
+ {db:"developers",design:"basic_info",view:"by_name",args:{reduce:false,key:"Jane"}}
+
+With this method we can send all data necessary to query views in the same structure:
+
+ {db:"developers",design:"basic_info",view:"by_name",args:{reduce:false},request:{keys:["Jane"]}}
+
+
+## Requirements
+Tested on node.js v0.4.7 and CouchDB 1.1.1
+
+PJsonCouch requires knowing the [CouchDB API](http://techzone.couchbase.com/sites/default/files/uploads/all/documentation/couchbase-api.html) and does not intend to overcome the logic behind the original API.
+
+## How is PJsonCouch organized?
+
+PJsonCouch is inspired on the CouchDB HTTP API structure, so is divide in 4 main blocks
+
+* Database Methods.
+* Document Methods / Local (non-replicating) Document Methods
+* Design Document Methods
+* Miscellaneous Methods
+
+
+
+## Examples
+
+How to connect to CouchDB without db definition and request a complex query to `_all_docs`
+
+ // Constructor without db definition
+ var test = PJsonCouch({protocol:"http",host:"127.0.0.1",port:5984});
+
+ // set a DB, this does not have callbackfuntion
+ test.setDB({db:"thisisatempdb"});
+
+ // Login if your DB is protected
+ test.login({user:"landeiro",password:"123"},function(r){
+ // Get all docs from DB, supports all args and request data from original couchdb API
+ test.queryDB({action:"_all_docs", args:{descending:true,startkey:"objmyid6",endkey:"objmyid2"}}, function(r){log("*queryDB start/endkey*",r);});
+ test.queryDB({action:"_all_docs", request:{keys:["objmyid1","objmyid7"]}}, function(r){log("*queryDB keys*",r);});
+ });
+
+
+How to connect to CouchDB with db definition and execute some docs operations
+
+ var test = PJsonCouch({protocol:"http",host:"127.0.0.1",port:5984,db:"mydatabase"});
+
+ // Docs for test
+ var docs = [{_id:"objmyid0",a:0},{_id:"objmyid1",a:1},{_id:"objmyid2",a:3}];
+
+ // Save bulk, supports all request data from original couchdb API
+ test.saveBulkDocs({docs:docs},function(r){
+ log("insert bulk",r);
+ // Get Doc, supports all arguments from original couchdb API
+ test.getDoc({id:"objmyid0"},function (gdoc) {
+ log("*get doc*",gdoc)
+ if (!gdoc.error) {
+ // Delete a Doc, supports all arguments from original couchdb API
+ test.deleteDoc({doc:gdoc}, function (r) { log("*deleted "+gdoc._id+"*",r);});
+ }
+ });
+ });
+
+
+
+Some random server operations
+
+
+ test.server({},function (r) {log("*welcome msg*",r);});
+ // Show active tasks
+ test.server({action:"_active_tasks"},function (r) {log("*active tasks*",r);});
+ // Start continuos replication database. Replication supports all configuration from original couchdb API
+ test.server({action:"_replicate",source:"thisisatempdb",target:"http://somedomain.com/land",continuous:true},function (r) {
+ log("*replicate*",r);
+ // Cancel continuos replication database, supports all configuration from original couchdb API
+ test.server({action:"_replicate",source:"thisisatempdb",target:"http://somedomain.com/land",continuous:true,cancel:true},function (r) {log("*cancel replication*",r);})
+
+ });
+
+
+Some random design doc operations
+
+ // List customers using view by_name from "Jane" to "Pedro"
+ test.queryDesign({design:"design_doc",list:"customers",view:"by_name",args:{startkey:"Jane",endkey:"Pedro"}},function (r) {log("*get list with view with args*",r);});
+
+ // Display a Doc using Show costumer, supports all arguments from original couchdb API
+ test.queryDesign({design:"design_doc",show:"customer",id:"3535e007bd9c765de0554c0a4900385b"},function (r) {log("*get show*",r);});
+
+ // Getting docs using view by_name with request keys ["Jane"] and argument limit=1
+ test.queryDesign({design:"design_doc",view:"by_name",args:{limit:1},request:{keys:["Jane","joey"]}},function (r) {log("*get view with request and args*",r);});
+
+
+### Errors can be configured to return a lot of debug, like request content and headers.
+
+Cannot connect do CouchDB
+
+ { error: 'request_to_couchdb',
+ detail:
+ { stack: 'Error: ECONNREFUSED, Connection refused\n at Socket._onConnect (net.js:576:18)\n at IOWatcher.onWritable [as callback] (net.js:165:12)',
+ message: 'ECONNREFUSED, Connection refused',
+ errno: 61,
+ code: 'ECONNREFUSED',
+ syscall: 'connect' },
+ debug:
+ { content: '""',
+ request:
+ { protocol: 'http',
+ host: '127.0.0.1',
+ port: 5984,
+ path: '/_log?bytes=2000',
+ method: 'GET',
+ headers: [Object],
+ agent: [Object] } } }
+
+Unauthorized
+
+ { error: 'unauthorized',
+ reason: 'You are not a server admin.',
+ debug:
+ { content: '""',
+ request:
+ { protocol: 'http',
+ host: '127.0.0.1',
+ port: 5984,
+ path: '/_active_tasks',
+ method: 'GET',
+ headers: [Object],
+ agent: [Object],
+ content_type: 'text/plain;charset=utf-8',
+ content_length: '64' },
+ resultHeaders:
+ { server: 'CouchDB/1.1.1 (Erlang OTP/R14B)',
+ location: 'http://127.0.0.1/_utils/session.html?return=%2F_active_tasks&reason=You%20are%20not%20a%20server%20admin.',
+ date: 'Tue, 26 Apr 2011 11:47:53 GMT',
+ 'content-type': 'text/plain;charset=utf-8',
+ 'content-length': '64',
+ 'cache-control': 'must-revalidate' } } }
+
+
+See more examples here.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.

0 comments on commit bb0f119

Please sign in to comment.