Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 647 lines (470 sloc) 16.471 kB
fc9a1f1 @dscape Changes to documentation
authored
1 # nano
9fc57cc @dscape Documentation
authored
2
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
3 minimalistic couchdb driver for node.js
9fc57cc @dscape Documentation
authored
4
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
5 `nano` features:
6
e0db616 @dscape [minor docs] readme typos
authored
7 * **minimalistic** - there is only a minimum of abstraction between you and
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
8 couchdb
9 * **pipes** - proxy requests from couchdb directly to your end user
e0db616 @dscape [minor docs] readme typos
authored
10 * **errors** - errors are proxied directly from couchdb: if you know couchdb
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
11 you already know `nano`
12
13
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
14 ## installation
9fc57cc @dscape Documentation
authored
15
fc9a1f1 @dscape Changes to documentation
authored
16 1. install [npm][1]
9fc57cc @dscape Documentation
authored
17 2. `npm install nano`
18
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
19 ## getting started
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
20
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
21 to use `nano` you need to connect it to your couchdb install, to do that:
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
22
23 ``` js
24 var nano = require('nano')('http://localhost:5984');
25 ```
26
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
27 to create a new database:
9fc57cc @dscape Documentation
authored
28
05b8eb5 @dscape [readme] syntax highlight
authored
29 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
30 nano.db.create('alice');
05b8eb5 @dscape [readme] syntax highlight
authored
31 ```
9fc57cc @dscape Documentation
authored
32
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
33 and to use it:
9fc57cc @dscape Documentation
authored
34
05b8eb5 @dscape [readme] syntax highlight
authored
35 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
36 var alice = nano.db.use('alice');
05b8eb5 @dscape [readme] syntax highlight
authored
37 ```
9fc57cc @dscape Documentation
authored
38
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
39 in this examples we didn't specify a `callback` function, the absence of a
40 callback means _"do this, ignore what happens"_.
41 in `nano` the callback function receives always three arguments:
9fc57cc @dscape Documentation
authored
42
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
43 * `err` - the error, if any
44 * `body` - the http _response body_ from couchdb, if no error.
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
45 json parsed body, binary for non json responses
46 * `header` - the http _response header_ from couchdb, if no error
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
47
48
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
49 a simple but complete example using callbacks is:
9fc57cc @dscape Documentation
authored
50
05b8eb5 @dscape [readme] syntax highlight
authored
51 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
52 var nano = require('nano')('http://localhost:5984');
53
54 // clean up the database we created previously
55 nano.db.destroy('alice', function() {
56 // create a new database
57 nano.db.create('alice', function() {
58 // specify the database we are going to use
59 var alice = nano.use('alice');
60 // and insert a document in it
61 alice.insert({ crazy: true }, 'rabbit', function(err, body, header) {
62 if (err) {
63 console.log('[alice.insert] ', err.message);
64 return;
65 }
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
66 console.log('you have inserted the rabbit.')
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
67 console.log(body);
05b8eb5 @dscape [readme] syntax highlight
authored
68 });
69 });
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
70 });
71 ```
72
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
73 if you run this example(after starting couchdb) you will see:
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
74
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
75 you have inserted the rabbit.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
76 { ok: true,
77 id: 'rabbit',
78 rev: '1-6e4cb465d49c0368ac3946506d26335d' }
79
95b6154 @fracek Add capitalization where needed
fracek authored
80 you can also see your document in [futon](http://localhost:5984/_utils).
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
81
ab717bf @dscape [docs feature] adds support for any request defaults
authored
82 ## configuration
83
84 configuring nano to use your database server is as simple as:
85
86 ``` js
87 var server = require('nano')('http://localhost:5984')
88 , db = server.use('foo')
89 ;
90 ```
91
92 however if you don't need to instrument database objects you can simply:
93
94 ``` js
95 // nano parses the url and knows this is a database
96 var db = require('nano')('http://localhost:5984/foo');
97 ```
98
99 you can also pass options to the require:
100
101 ``` js
102 // nano parses the url and knows this is a database
103 var db = require('nano')('http://localhost:5984/foo');
104 ```
105
106 to specify further configuration options you can pass an object literal instead:
107
108 ``` js
109 // nano parses the url and knows this is a database
110 var db = require('nano')(
111 { "url" : "http://localhost:5984/foo"
112 , "request_options" : { "proxy" : "http://someproxy" }
113 , "log" : function (id, args) {
114 console.log(id, args);
115 }
116 });
117 ```
118 please check [request] for more information on the defaults. they support features like cookie jar, proxies, ssl, etc.
119
120 ### pool size
121
122 a very important configuration parameter if you have a high traffic website and are using nano is setting up the `pool.size`. by default the node.js http agent (client) has a certain size of active connections that can run simultaneously, while others are kept in a queue.
123
124 you can increase the size using `request_options` if this is problematic, and refer to the [request] documentation and examples for further clarification
125
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
126 ## database functions
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
127
128 ### nano.db.create(name, [callback])
129
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
130 creates a couchdb database with the given `name`.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
131
132 ``` js
133 nano.db.create('alice', function(err, body) {
134 if (!err) {
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
135 console.log('database alice created!');
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
136 }
137 });
05b8eb5 @dscape [readme] syntax highlight
authored
138 ```
9fc57cc @dscape Documentation
authored
139
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
140 ### nano.db.get(name, [callback])
141
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
142 get informations about `name`.
9fc57cc @dscape Documentation
authored
143
05b8eb5 @dscape [readme] syntax highlight
authored
144 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
145 nano.db.get('alice', function(err, body) {
146 if (!err) {
147 console.log(body);
148 }
149 });
05b8eb5 @dscape [readme] syntax highlight
authored
150 ```
d5f4372 @dscape Changes to documentation
authored
151
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
152 ### nano.db.destroy(name, [callback])
153
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
154 destroys `name`.
d5f4372 @dscape Changes to documentation
authored
155
05b8eb5 @dscape [readme] syntax highlight
authored
156 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
157 nano.db.destroy('alice');
05b8eb5 @dscape [readme] syntax highlight
authored
158 ```
d5f4372 @dscape Changes to documentation
authored
159
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
160 even though this examples looks sync it is an async function.
d5f4372 @dscape Changes to documentation
authored
161
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
162 ### nano.db.list([callback])
d5f4372 @dscape Changes to documentation
authored
163
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
164 lists all the databases in couchdb
9fc57cc @dscape Documentation
authored
165
05b8eb5 @dscape [readme] syntax highlight
authored
166 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
167 nano.db.list(function(err, body) {
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
168 // body is an array
95b6154 @fracek Add capitalization where needed
fracek authored
169 body.forEach(function(db) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
170 console.log(db);
171 });
172 });
05b8eb5 @dscape [readme] syntax highlight
authored
173 ```
9fc57cc @dscape Documentation
authored
174
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
175 ### nano.db.compact(name, [designname], [callback])
5d75c0e @dscape updated references
authored
176
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
177 compacts `name`, if `designname` is specified also compacts its
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
178 views.
179
180 ### nano.db.replicate(source, target, [opts], [callback])
181
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
182 replicates `source` on `target` with options `opts`. `target`
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
183 has to exist, add `create_target:true` to `opts` to create it prior to
184 replication.
185
186 ``` js
187 nano.db.replicate('alice', 'http://admin:password@otherhost.com:5984/alice',
188 { create_target:true }, function(err, body) {
189 if (!err)
190 console.log(body);
191 });
192 ```
193
194 ### nano.db.changes(name, [params], [callback])
63940c4 @dscape fixes to readme
authored
195
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
196 asks for the changes feed of `name`, `params` contains additions
e0db616 @dscape [minor docs] readme typos
authored
197 to the query string.
9fc57cc @dscape Documentation
authored
198
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
199 ``` js
200 nano.db.changes('alice', function(err, body) {
7d6e033 @dscape [feature] follow
authored
201 if (!err) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
202 console.log(body);
7d6e033 @dscape [feature] follow
authored
203 }
204 });
205 ```
206
207 ### nano.db.follow(name, [params], [callback])
208
209 uses [follow] to create a solid changes feed. please consult follow documentation for more information as this is a very complete api on it's own
210
211 ``` js
212 var feed = db.follow({since: "now"});
213 feed.on('change', function (change) {
214 console.log("change: ", change);
215 });
216 feed.follow();
217 process.nextTick(function () {
218 db.insert({"bar": "baz"}, "bar");
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
219 });
220 ```
221
222 ### nano.use(name)
223
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
224 creates a scope where you operate inside `name`.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
225
226 ``` js
227 var alice = nano.use('alice');
228 alice.insert({ crazy: true }, 'rabbit', function(err, body) {
229 // do something
230 });
231 ```
232
233 ### nano.db.use(name)
9fc57cc @dscape Documentation
authored
234
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
235 alias for `nano.use`
9fc57cc @dscape Documentation
authored
236
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
237 ### nano.db.scope(name)
9fc57cc @dscape Documentation
authored
238
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
239 alias for `nano.use`
9fc57cc @dscape Documentation
authored
240
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
241 ### nano.scope(name)
9fc57cc @dscape Documentation
authored
242
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
243 alias for `nano.use`
9fc57cc @dscape Documentation
authored
244
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
245 ### nano.request(opts, [callback])
9fc57cc @dscape Documentation
authored
246
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
247 makes a request to couchdb, the available `opts` are:
9fc57cc @dscape Documentation
authored
248
c10c6fb @dscape [docs] adds documentation for setting headers
authored
249 * `opts.db` – the database name
250 * `opts.method` – the http method, defaults to `get`
251 * `opts.path` – the full path of the request, overrides `opts.doc` and
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
252 `opts.att`
c10c6fb @dscape [docs] adds documentation for setting headers
authored
253 * `opts.doc` – the document name
254 * `opts.att` – the attachment name
255 * `opts.content_type` – the content type of the request, default to `json`
256 * `opts.headers` – additional http headers, overrides existing ones
257 * `opts.body` – the document or attachment body
258 * `opts.encoding` – the encoding for attachments
9fc57cc @dscape Documentation
authored
259
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
260 ### nano.relax(opts, [callback])
9fc57cc @dscape Documentation
authored
261
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
262 alias for `nano.request`
9fc57cc @dscape Documentation
authored
263
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
264 ### nano.dinosaur(opts, [callback])
fc9a1f1 @dscape Changes to documentation
authored
265
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
266 alias for `nano.request`
fc9a1f1 @dscape Changes to documentation
authored
267
e0db616 @dscape [minor docs] readme typos
authored
268 _
269 / '_) WAT U SAY!
270 _.----._/ /
271 / /
272 _/ ( | ( |
273 /__.-|_|--|_l
274
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
275 ### nano.config
276
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
277 an object containing the nano configurations, possible keys are:
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
278
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
279 * `url` - the couchdb url
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
280 * `db` - the database name
281
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
282 ## document functions
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
283
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
284 ### db.insert(doc, [docname], [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
285
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
286 inserts `doc` in the database with an optional `docname`.
68d827e @thiagoarrais Remove trailing spaces only
thiagoarrais authored
287
05b8eb5 @dscape [readme] syntax highlight
authored
288 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
289 var alice = nano.use('alice');
290 alice.insert({ crazy: true }, 'rabbit', function(err, body) {
291 if (!err)
292 console.log(body);
293 });
05b8eb5 @dscape [readme] syntax highlight
authored
294 ```
9fc57cc @dscape Documentation
authored
295
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
296 ### db.destroy(docname, rev, [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
297
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
298 removes revision `rev` of `docname` from couchdb.
fc9a1f1 @dscape Changes to documentation
authored
299
05b8eb5 @dscape [readme] syntax highlight
authored
300 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
301 alice.destroy('alice', '3-66c01cdf99e84c83a9b3fe65b88db8c0', function(err, body) {
302 if (!err)
303 console.log(body);
304 });
05b8eb5 @dscape [readme] syntax highlight
authored
305 ```
fc9a1f1 @dscape Changes to documentation
authored
306
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
307 ### db.get(docname, [params], [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
308
e0db616 @dscape [minor docs] readme typos
authored
309 gets `docname` from the database with optional query string
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
310 additions `params`.
d1a2919 @dscape Added params support for list
authored
311
05b8eb5 @dscape [readme] syntax highlight
authored
312 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
313 alice.get('rabbit', { revs_info: true }, function(err, body) {
314 if (!err)
315 console.log(body);
316 });
05b8eb5 @dscape [readme] syntax highlight
authored
317 ```
d1a2919 @dscape Added params support for list
authored
318
710d49e @jlank Updated section in README.md pertaining to db.head(doc, [callback]). …
jlank authored
319 ### db.head(docname, [callback])
ca2b3ad @dscape [docs] adds readme for head
authored
320
321 same as `get` but lightweight version that returns headers only.
322
323 ``` js
710d49e @jlank Updated section in README.md pertaining to db.head(doc, [callback]). …
jlank authored
324 alice.head('rabbit', function(err, _, headers) {
ca2b3ad @dscape [docs] adds readme for head
authored
325 if (!err)
326 console.log(headers);
327 });
328 ```
329
11cd741 @jlank [docs] adds readme for copy
jlank authored
330 ### db.copy(src_doc, dest_doc, opts, [callback])
331
332 `copy` the contents (and attachments) of a document
333 to a new document, or overwrite an existing target document
334
335 ``` js
336 alice.copy('rabbit', 'rabbit2', { overwrite: true }, function(err, _, headers) {
337 if (!err)
338 console.log(headers);
339 });
340 ```
341
342
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
343 ### db.bulk(docs, [params], [callback])
344
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
345 bulk operations(update/delete/insert) on the database, refer to the
ad2353e @cliffano Fix couchdb doc links to HTTP Bulk Document API.
cliffano authored
346 [couchdb doc](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API).
08969d7 @dscape Pipe Support
authored
347
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
348 ### db.list([params], [callback])
349
e0db616 @dscape [minor docs] readme typos
authored
350 list all the docs in the database with optional query string additions `params`.
08969d7 @dscape Pipe Support
authored
351
05b8eb5 @dscape [readme] syntax highlight
authored
352 ``` js
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
353 alice.list(function(err, body) {
354 if (!err) {
95b6154 @fracek Add capitalization where needed
fracek authored
355 body.rows.forEach(function(doc) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
356 console.log(doc);
357 });
358 }
359 });
05b8eb5 @dscape [readme] syntax highlight
authored
360 ```
08969d7 @dscape Pipe Support
authored
361
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
362 ### db.fetch(docnames, [params], [callback])
fc9a1f1 @dscape Changes to documentation
authored
363
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
364 bulk fetch of the database documents, `docnames` are specified as per
ad2353e @cliffano Fix couchdb doc links to HTTP Bulk Document API.
cliffano authored
365 [couchdb doc](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API).
e0db616 @dscape [minor docs] readme typos
authored
366 additional query string `params` can be specified, `include_doc` is always set
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
367 to `true`.
9fc57cc @dscape Documentation
authored
368
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
369 ## attachments functions
9fc57cc @dscape Documentation
authored
370
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
371 ### db.attachment.insert(docname, attname, att, contenttype, [params], [callback])
9fc57cc @dscape Documentation
authored
372
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
373 inserts an attachment `attname` to `docname`, in most cases
374 `params.rev` is required. refer to the
375 [doc](http://wiki.apache.org/couchdb/http_document_api) for more details.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
376
377 ``` js
378 var fs = require('fs');
379
95b6154 @fracek Add capitalization where needed
fracek authored
380 fs.readFile('rabbit.png', function(err, data) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
381 if (!err) {
382 alice.attachment.insert('rabbit', 'rabbit.png', data, 'image/png',
383 { rev: '12-150985a725ec88be471921a54ce91452' }, function(err, body) {
384 if (!err)
385 console.log(body);
386 });
387 }
388 });
389 ```
390
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
391 or using `pipe`:
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
392
393 ``` js
394 var fs = require('fs');
9fc57cc @dscape Documentation
authored
395
95b6154 @fracek Add capitalization where needed
fracek authored
396 fs.createReadStream('rabbit.png').pipe(
5f77e92 @dscape [docs fix minor] fixes documentation
authored
397 alice.attachment.insert('new', 'rab.png', null, 'image/png')
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
398 );
399 ```
400
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
401 ### db.attachment.get(docname, attname, [params], [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
402
e0db616 @dscape [minor docs] readme typos
authored
403 get `docname`'s attachment `attname` with optional query string additions
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
404 `params`.
405
406 ``` js
407 var fs = require('fs');
408
409 alice.attachment.get('rabbit', 'rabbit.png', function(err, body) {
410 if (!err) {
95b6154 @fracek Add capitalization where needed
fracek authored
411 fs.writeFile('rabbit.png', body);
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
412 }
413 });
414 ```
415
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
416 or using `pipe`:
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
417
418 ``` js
419 var fs = require('fs');
420
95b6154 @fracek Add capitalization where needed
fracek authored
421 alice.attachment.get('rabbit', 'rabbit.png').pipe(fs.createWriteStream('rabbit.png'));
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
422 ```
423
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
424 ### db.attachment.destroy(docname, attname, rev, [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
425
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
426 destroy attachment `attname` of `docname`'s revision `rev`.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
427
428 ``` js
429 alice.attachment.destroy('rabbit', 'rabbit.png',
430 '1-4701d73a08ce5c2f2983bf7c9ffd3320', function(err, body) {
431 if (!err)
432 console.log(body);
433 });
434 ```
435
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
436 ## views and design functions
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
437
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
438 ### db.view(designname, viewname, [params], [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
439
e0db616 @dscape [minor docs] readme typos
authored
440 calls a view of the specified design with optional query string additions
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
441 `params`.
442
443 ``` js
444 alice.view('characters', 'crazy_ones', function(err, body) {
445 if (!err) {
95b6154 @fracek Add capitalization where needed
fracek authored
446 body.rows.forEach(function(doc) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
447 console.log(doc.value);
448 });
449 }
450 });
451 ```
452
2f16256 @dscape [merge] merges new test suite
authored
453 ### db.atomic(designname, updatename, docname, [body], [callback])
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
454
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
455 calls the design's update function with the specified doc in input.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
456
2f16256 @dscape [merge] merges new test suite
authored
457 ``` js
458 db.atomic("update", "inplace", "foobar",
459 {field: "foo", value: "bar"}, function (error, response) {
8091dcb @dscape [docs] better cookies
authored
460 assert.equal(error, undefined, "failed to update");
461 assert.equal(response.foo, "bar", "update worked");
2f16256 @dscape [merge] merges new test suite
authored
462 });
463 ```
464
465 check out the tests for a fully functioning example.
466
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
467 ## using cookie authentication
468
8091dcb @dscape [docs] better cookies
authored
469 nano supports making requests using couchdb's [cookie authentication](http://guide.couchdb.org/editions/1/en/security.html#cookies) functionality. there's a [step-by-step guide here](http://mahoney.eu/2012/05/23/couchdb-cookie-authentication-nodejs-nano/), but essentially you just:
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
470
471 ``` js
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
472 var nano = require('nano')('http://localhost:5984')
473 , username = 'user'
474 , userpass = 'pass'
475 , callback = console.log // this would normally be some callback
476 , cookies = {} // store cookies, normally redis or something
477 ;
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
478
9e15871 @dscape [docs minor] shows the new auth apis
authored
479 nano.auth(username, userpass, function (err, body, headers) {
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
480 if (err) {
481 return callback(err);
482 }
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
483
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
484 if (headers && headers['set-cookie']) {
485 cookies[user] = headers['set-cookie'];
486 }
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
487
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
488 callback(null, "It worked");
489 });
490 ```
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
491
066d7cf @dscape [minor] introduced trash
authored
492 reusing a cookie:
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
493
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
494 ``` js
495 var auth = "some stored cookie"
496 , callback = console.log // this would normally be some callback
497 , nano require('nano')(
498 { url : 'http://localhost:5984/alice', cookie: 'AuthSession=' + auth });
499 ;
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
500
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
501 alice.insert(doc, function (err, body, headers) {
502 if (err) {
503 return callback(err);
504 }
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
505
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
506 // change the cookie if couchdb tells us too
507 if (headers && headers['set-cookie']) {
508 auth = headers['set-cookie'];
509 }
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
510
5d328da @dscape [cookies docs minor] minor changes like removing references to expres…
authored
511 callback(null, "It worked");
512 });
f57beae @userIsNaN Updated cookie authentication documentation
userIsNaN authored
513 ```
514
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
515 ## advanced features
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
516
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
517 ### extending nano
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
518
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
519 nano is minimalistic but you can add your own features with
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
520 `nano.request(opts, callback)`
521
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
522 for example, to create a function to retrieve a specific revision of the
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
523 `rabbit` document:
524
525 ``` js
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
526 function getrabbitrev(rev, callback) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
527 nano.request({ db: 'alice',
528 doc: 'rabbit',
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
529 method: 'get',
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
530 params: { rev: rev }
531 }, callback);
532 }
533
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
534 getrabbitrev('4-2e6cdc4c7e26b745c2881a24e0eeece2', function(err, body) {
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
535 if (!err) {
536 console.log(body);
537 }
538 });
539 ```
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
540 ### pipes
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
541
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
542 you can pipe in nano like in any other stream.
543 for example if our `rabbit` document has an attachment with name `picture.png`
544 (with a picture of our white rabbit, of course!) you can pipe it to a `writable
545 stream`
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
546
547 ``` js
548 var fs = require('fs'),
cc302c6 @dscape [docs] fixes issue on `pipe` example
authored
549 nano = require('nano')('http://127.0.0.1:5984/');
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
550 var alice = nano.use('alice');
95b6154 @fracek Add capitalization where needed
fracek authored
551 alice.attachment.get('rabbit', 'picture.png').pipe(fs.createWriteStream('/tmp/rabbit.png'));
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
552 ```
553
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
554 then open `/tmp/rabbit.png` and you will see the rabbit picture.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
555
556
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
557 ## tutorials & screencasts
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
558
559 * screencast: [couchdb and nano](http://nodetuts.com/tutorials/30-couchdb-and-nano.html#video)
560 * article: [nano - a minimalistic couchdb client for nodejs](http://writings.nunojob.com/2011/08/nano-minimalistic-couchdb-client-for-nodejs.html)
561 * article: [getting started with node.js and couchdb](http://writings.nunojob.com/2011/09/getting-started-with-nodejs-and-couchdb.html)
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
562 * article: [document update handler support](http://jackhq.tumblr.com/post/16035106690/nano-v1-2-x-document-update-handler-support-v1-2-x)
103c0bc @dscape [docs] adds nano 3 blogpost
authored
563 * article: [nano 3](http://writings.nunojob.com/2012/05/Nano-3.html)
8091dcb @dscape [docs] better cookies
authored
564 * article: [securing a site with couchdb cookie authentication using node.js and nano](http://mahoney.eu/2012/05/23/couchdb-cookie-authentication-nodejs-nano/)
9ee0f2d @dscape [docs] adds copy article to readme
authored
565 * article: [adding copy to nano](http://blog.jlank.com/2012/07/04/adding-copy-to-nano/)
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
566
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
567 ## roadmap
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
568
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
569 check [issues][2]
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
570
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
571 ## tests
f94ce71 @dscape [readme] instructions to run tests for contributors
authored
572
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
573 to run (and configure) the test suite simply:
6754d54 @dscape 0.8.5 more flexible tests
authored
574
05b8eb5 @dscape [readme] syntax highlight
authored
575 ``` sh
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
576 cd nano
36f047b @dscape [docs fix] testing instructions;
authored
577 npm install
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
578 npm test
05b8eb5 @dscape [readme] syntax highlight
authored
579 ```
6754d54 @dscape 0.8.5 more flexible tests
authored
580
f94ce71 @dscape [readme] instructions to run tests for contributors
authored
581 after adding a new test you can run it individually (with verbose output) using:
9fc57cc @dscape Documentation
authored
582
f94ce71 @dscape [readme] instructions to run tests for contributors
authored
583 ``` sh
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
584 nano_env=testing node tests/doc/list.js list_doc_params
f94ce71 @dscape [readme] instructions to run tests for contributors
authored
585 ```
7d9c7b8 @dscape Changes to documentation
authored
586
f94ce71 @dscape [readme] instructions to run tests for contributors
authored
587 where `list_doc_params` is the test name.
9fc57cc @dscape Documentation
authored
588
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
589 ## contribute
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
590
bc7a10a @dscape [docs] adds testing instructions
authored
591 everyone is welcome to contribute with patches, bug-fixes and new features
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
592
593 1. create an [issue][2] on github so the community can comment on your idea
594 2. fork `nano` in github
595 3. create a new branch `git checkout -b my_branch`
596 4. create tests for the changes you made
597 5. make sure you pass both existing and newly inserted tests
598 6. commit your changes
599 7. push to your branch `git push origin my_branch`
600 8. create a pull request
601
bc7a10a @dscape [docs] adds testing instructions
authored
602 to run tests make sure you npm test but also run tests without mocks:
603
604 ``` sh
605 npm run nock_off
606 ```
607
8091dcb @dscape [docs] better cookies
authored
608 check this [blogpost](http://writings.nunojob.com/2012/05/Mock-HTTP-Integration-Testing-in-Node.js-using-Nock-and-Specify.html) to learn more about how to write your own tests.
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
609
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
610 ## meta
9fc57cc @dscape Documentation
authored
611
612 _
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
613 / _) roar! i'm a vegan!
9fc57cc @dscape Documentation
authored
614 .-^^^-/ /
615 __/ /
7d9c7b8 @dscape Changes to documentation
authored
616 /__.|_|-|_| cannes est superb
9fc57cc @dscape Documentation
authored
617
fc9a1f1 @dscape Changes to documentation
authored
618 * code: `git clone git://github.com/dscape/nano.git`
619 * home: <http://github.com/dscape/nano>
620 * bugs: <http://github.com/dscape/nano/issues>
6910cb0 @dscape [readme] build status on end
authored
621 * build: [![build status](https://secure.travis-ci.org/dscape/nano.png)](http://travis-ci.org/dscape/nano)
9fc57cc @dscape Documentation
authored
622
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
623 `(oo)--',-` in [caos][3]
9fc57cc @dscape Documentation
authored
624
625 [1]: http://npmjs.org
626 [2]: http://github.com/dscape/nano/issues
2635d8f @dscape Added link to docs
authored
627 [3]: http://caos.di.uminho.pt/
9e26976 @thiagoarrais Changes the callback parameter order
thiagoarrais authored
628 [4]: https://github.com/dscape/nano/blob/master/cfg/couch.example.js
7d6e033 @dscape [feature] follow
authored
629 [follow]: https://github.com/iriscouch/follow
ab717bf @dscape [docs feature] adds support for any request defaults
authored
630 [request]: https://github.com/mikeal/request
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
631
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
632 ## license
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
633
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
634 copyright 2011 nuno job <nunojob.com> (oo)--',--
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
635
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
636 licensed under the apache license, version 2.0 (the "license");
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
637 you may not use this file except in compliance with the license.
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
638 you may obtain a copy of the license at
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
639
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
640 http://www.apache.org/licenses/license-2.0
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
641
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
642 unless required by applicable law or agreed to in writing, software
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
643 distributed under the license is distributed on an "as is" basis,
644 without warranties or conditions of any kind, either express or implied.
53bc415 @fracek Implement suggestions by @thiagoarrais
fracek authored
645 see the license for the specific language governing permissions and
d928938 @fracek Rewrite the README to include functions documentation and some examples
fracek authored
646 limitations under the license.
Something went wrong with that request. Please try again.